단일 바이너리, markdown 파일, 파생 인덱스

1. 1

   훅LLM 불필요

   에이전트 CLI가 라이프사이클 훅을 실행합니다. 200 ms 예산 안에서 fire and forget으로 동작합니다. 네이티브 훅은 이벤트를 로컬에 스풀하고, 분리된 헬퍼가 이를 전달합니다. 서버는 202로 응답하고, 포화 상태에서는 429를 돌려줍니다.

2. 2

   민감 정보 제거LLM 불필요

   /hook 라우터가 시크릿을 제거하고 크기를 제한합니다. 신뢰할 수 없는 텍스트가 스토어로 들어가는 경로는 여기뿐입니다.

3. 3

   단일 라이터LLM 불필요

   정제된 이벤트는 큐 하나에 들어가고, 유일한 쓰기 커넥션을 가진 스레드 하나가 큐를 비웁니다.

4. 4

   관찰 기록LLM 불필요

   이벤트는 운영용 감사 추적으로 SQLite에 쌓입니다. 세션을 제한된 범위로 투영한 것이며 전체 트랜스크립트가 되는 일은 없습니다.

5. 5

   세션 종료LLM 불필요

   모델 없이 규칙만으로 관찰 기록을 sessions/<id>.md로 만들고, 다음 에이전트를 위한 Handoff 행을 엽니다. 모두 트랜잭션 하나에서 처리됩니다.

6. 6

   통합LLM 선택

   제공자를 설정하면 LLM이 요약을 다시 쓰거나 concepts/, decisions/, gotchas/, procedures/로 펼칩니다. 재시도 가능한 큐에서 실행되므로 훅 지연 시간에 영향을 주지 않습니다.

7. 7

   커밋과 인덱싱LLM 불필요

   페이지 쓰기는 매번 원자적(tmp, rename, fsync)이고, git에 커밋되며, 해당 행과 같은 SQLite 트랜잭션 안에서 인덱싱됩니다.

8. 8

   쿼리와 브리핑LLM 불필요

   memory_query가 인덱스를 검색합니다. 다음 SessionStart에서 훅이 그 디렉터리에 열려 있는 인수인계와 구조화된 브리핑을 가져옵니다.

• 전문 검색

  페이지 제목과 본문에 대한 SQLite FTS5. 단순 쿼리에서는 불용어를 걸러 냅니다.

• 엔티티 매칭

  프런트매터의 entities와 tags에서 뽑은 이름의 어휘 인덱스. 역페이지 빈도로 가중치를 줍니다.

• 그래프 이웃

  링크 테이블에서 한 홉: 위키링크, markdown 링크, 타입 엣지, 프로젝트 간 링크. 그래프 데이터베이스 없이 일반 SQL입니다.

• 관찰 기록

  프로젝트의 원본 관찰 기록에 대한 전문 검색. 일치하는 세션마다 가장 잘 맞는 관찰 기록 하나로 자기 세션 페이지에 한 번씩 투표하므로, 페이지에 담기지 못한 세부 내용으로도 그 세션을 찾을 수 있습니다. 3.0부터 기본으로 켜져 있습니다.

• 벡터, 선택 사항

  프로세스 내 로컬 모델이 만든 임베딩에 대한 코사인 유사도. 2.0부터 기본으로 켜져 있지만 필수는 아니며, 의도적으로 브루트 포스입니다.

융합 이후

• k=60의 Reciprocal Rank Fusion이 스트림을 순위 기준으로 합치므로, 어떤 스트림도 점수 보정이 필요 없습니다.
• 그다음 상한이 있는 권위도 배수가 근소한 경합을 관리되는 규칙, 결정, 절차, 주의점 쪽으로 살짝 기울입니다. 에피소드성 페이지와 과거 기록 페이지도 계속 검색되며, 아예 제외되는 것은 없습니다.
• 선택적 LLM 리랭크: 쿼리당 호출 한 번, 제목과 스니펫 최대 30개가 대상입니다. 실패하면 로컬 순서를 그대로 씁니다. 로컬 리랭커는 아직 없습니다.
• 컴파일된 페이지에서 아무것도 찾지 못하면 원본 관찰 기록에 대한 제한된 검색이 raw_hits를 돌려줍니다.
• 필터는 랭킹 전에 적용됩니다. kind, tag, tier와 경로 접두사가 모든 스트림을 좁히기 때문에, 드문 페이지가 흔한 페이지에 밀려나지 않습니다.
• 선택 신호 두 가지가 있으며 기본값은 0입니다. 하나는 '오래됨'이나 '틀림' 피드백이 열려 있는 페이지의 권위를 낮추고, 다른 하나는 같은 세션이 비슷한 질의에서 읽었거나 도움이 됐다고 표시한 페이지를 끌어올립니다. 페이지를 다시 쓰면 둘 다 사라집니다.
• explain=true를 넘기면 결과마다 스트림별 순위, RRF 기여도, 배수를 볼 수 있습니다.

불변식 16개가 모두 담긴 ARCHITECTURE.md설계 결정과 기각한 선택지