지식 베이스 하이브리드 검색 (전문검색 + 벡터 + IDF (+trgm/문맥), 가중 RRF 융합, Slack 나이 감쇠).

정확 토큰(에러 문자열, 설정 키, 호스트명)과 자연어 개념 질문 모두에 동작한다. source: 'slack' | 'markdown' | 'gitlog' | 'code' | 'note' 필터. project: 스코프 이름 (토큰에 기본 프로젝트가 있으면 자동 적용 — 전체를 보려면 project="*"). 노트 결과의 project 필드는 그 기록의 소속 프로젝트(null=팀 공용)다. 스코프 검색에서 다른 프로젝트의 노트는 하향되고 matched에 'other-project'가 붙는다 — 증상이 같아도 프로젝트가 다르면 원인이 다를 수 있으니 주의해서 읽어라. expand=1~2면 매치된 청크의 이웃 청크를 context 필드로 복원한다(잘린 문맥 방지). rerank=true면 소형 LLM이 상위 후보를 재채점한다 (느리고 비용 발생 — 정밀도가 중요할 때만). 반환: [{document_id, score, source, ..., snippet, matched, context}]

문서 원문 조회. Slack 스레드면 증류 결과(distilled)도 포함된다. context=1이면 문서의 청크 목록(헤딩 단위)도 함께 반환한다.

인덱싱된 소스 카탈로그: 소스/구획별 문서 수·최근 갱신·설명("무엇을 잘 답하나"), 프로젝트 목록. 무엇이 검색 가능한지 파악할 때(도구 선택 전에) 먼저 호출하라.

주제에 대해 실증된 활동(스레드 참여, 커밋)이 있는 사람을 찾는다. 검색 상위 문서들의 참여자/작성자 메타데이터를 집계한 결과다.

최근 N일 내 갱신된 문서(커밋/스레드/문서). source로 필터 가능.

소스 저장소 위 ripgrep 정확 매칭. 에러 문자열·심볼·설정 키의 정의/사용처를 찾을 때. repo는 kb.toml [code_repos]에 등록된 이름 (생략 시 전체). regex=false면 리터럴 매칭.

개발 중 내린 의사결정을 지식 베이스에 기록한다 (기록 즉시 팀 전체 검색 가능).

언제 쓰나: 아키텍처/라이브러리/스키마 선택, 트레이드오프 판단, 컨벤션 결정 등 나중에 "왜 이렇게 했지?"가 나올 만한 모든 결정. title은 검색될 한 줄 요약(예: "세션 스토어를 Redis에서 Postgres로 변경"). 같은 title로 다시 기록하면 내용이 갱신된다. author에는 자신의 이름/에이전트명을 넣어라. code_refs: 이 결정이 참조하는 코드 경로 목록 — 해당 파일이 나중에 바뀌면 재검증 대상으로 표시된다. supersedes: 이 결정이 대체하는 옛 결정의 document_id (번복 추적). project: 특정 프로젝트/저장소에 한정된 결정이면 반드시 프로젝트 이름을 넣어라 (미지정 = 팀 공용으로 모든 프로젝트 검색에 동급 노출). 스코프 검색에서 다른 프로젝트의 노트는 하향 표시되므로, 이 필드가 오해를 막는다. 이름은 list_sources의 projects 목록 기준 — 저장소 이름을 넣으면 소유 프로젝트로 자동 교정되고(모노레포), 등록되지 않은 이름은 버려지고 팀 공용으로 기록된다 (응답의 project/project_hint 확인). 응답의 similar_existing에 유사 기존 기록이 있으면 중복 기록 대신 갱신을 고려하라 — 단, 후보의 project가 다르면 같은 증상이라도 원인이 다를 수 있으니 덮어쓰지 마라.

삽질·버그·실수에서 얻은 교훈을 기록한다. 같은 문제를 다시 밟지 않기 위한 핵심 도구.

언제 쓰나: 원인 파악에 30분 이상 쓴 버그, 문서와 다르게 동작한 것, 함정이 있는 설정, 재발 방지책이 있는 모든 문제. title에는 증상을 검색될 형태로 (예: "pgvector HNSW가 2000차원 초과에서 인덱스 생성 실패"). prevention에는 다음 사람이 지켜야 할 구체적 수칙을 적어라. code_refs: 관련 코드 경로 목록 — 그 파일이 바뀌면 이 교훈이 재검증 대상으로 표시된다. project: 특정 프로젝트/저장소에서만 성립하는 교훈이면 반드시 프로젝트 이름을 넣어라 (미지정 = 팀 공용). 다른 프로젝트의 유사 증상과 섞이는 오해를 막는다. 이름은 list_sources의 projects 목록 기준 — 저장소 이름은 소유 프로젝트로 자동 교정되고, 등록되지 않은 이름은 버려진다 (응답의 project/project_hint 확인).

결정도 교훈도 아닌 일반 지식 메모(조사 결과, 운영 절차, 링크 모음 등)를 기록한다.

project: 특정 프로젝트에 한정된 메모면 프로젝트 이름을 넣어라 (미지정 = 팀 공용). 이름은 list_sources의 projects 목록 기준 — 저장소 이름은 소유 프로젝트로 자동 교정되고, 등록되지 않은 이름은 버려진다 (응답의 project/project_hint 확인).

작업을 시작하기 전에 호출하라: 주제와 관련해 과거에 기록된 교훈(learning)과 의사결정(decision)을 찾아준다. 같은 실수를 반복하지 않기 위한 사전 점검 도구다.

topic에는 하려는 작업을 자연어로 (예: "pgvector 인덱스 마이그레이션", "Slack export 파싱"). 결과가 있으면 반드시 get_document로 예방책을 읽어라. 대체된(superseded) 노트는 제외된다. stale=true 표시는 참조 코드가 그 후 변경되어 재검증이 필요하다는 뜻 — 내용을 그대로 믿지 말고 현재 코드와 대조하라. project: 스코프 이름 (토큰에 기본 프로젝트가 있으면 자동 적용, 전체는 "*"). 결과의 project는 그 노트가 기록된 프로젝트(null=팀 공용) — 다른 프로젝트의 노트는 하향되고 other_project=true로 표시된다. 증상이 같아도 프로젝트가 다르면 원인이 다를 수 있으니 그대로 적용하지 말고 현재 프로젝트에서 재확인하라.

파일별 요약 인덱스 검색 (subsystem_index): "이 기능이 어느 파일에 구현돼 있나" 같은 저장소 구조 질문용. 파일 단위 요약(file_summary)과 경로+심볼 레코드(file_head)만 대상으로 하므로 search보다 파일 위치 특정에 강하다. 정확 문자열 매칭은 search_code(ripgrep)를 쓰라.

최근 Pull Request 목록/검색 (github_prs 커넥터 필요). query를 주면 관련도순, 없으면 최신순. PR 본문·리뷰 코멘트가 인덱싱되어 있어 "이거 최근에 누가 건드렸지" 류 질문에 답한다.

검색 결과 품질 피드백. 검색 결과가 실제로 문제를 해결했으면 useful=true, 엉뚱했으면 false로 남겨라 — 무응답 쿼리와 함께 골든셋/커넥터 백로그의 재료가 된다.

재검증이 필요한 노트 큐 — 대시보드 '재검증 큐'와 동일한 기준·순서. 참조 코드(code_refs)가 그 후 변경된 노트(reason='code' — 지금 틀렸을 수 있어 급함)가 먼저, 마지막 검증이 days일 이상 지난 노트(reason='age')가 그다음. superseded 노트는 제외. reason 파라미터('code'|'age')로 사유를 좁힐 수 있다.

재검증 워크플로: 각 항목을 get_document로 열어 내용(특히 stale_refs에 적힌 파일)을 현재 코드와 대조하라 → 여전히 정확하면 verify_note(document_id), 세부만 낡았으면 같은 title로 record_* 재기록(멱등 갱신), 결론이 뒤집혔으면 새 기록 + supersedes. 확신이 없으면 건드리지 말 것 — 잘못된 '검증됨' 표시는 미검증보다 해롭다. project가 자기 프로젝트와 다른 노트는 그 프로젝트의 코드 기준으로만 판정할 수 있으니 함부로 수정하지 마라. counts는 큐 전체 규모다 — results가 limit에 잘려도 남은 양을 알 수 있다.

노트(결정/교훈)를 재검증 완료로 표시한다 — 내용이 여전히 유효함을 확인했을 때. verified_at이 갱신되고 stale 플래그가 해제된다.