agent-knowledge

AI 코딩 어시스턴트를 위한 세션 간 메모리 및 회상 -- Claude Code, Cursor, OpenCode, Cline, Continue.dev, Aider와 즉시 호환됩니다. Git 동기화 지식 베이스, 하이브리드 의미론적+TF-IDF 검색, 비밀 정보 스크러빙을 포함한 자동 증류 기능을 제공합니다.

벤치마크: longmemeval_s에서 R@5 = 97.2% (sparse) / 98.8% (hybrid), 더 어려운 longmemeval_m 분할에서 86.0% (sparse) / 88.4% (hybrid) -- 공개 LongMemEval 학술 벤치마크(Wu et al. 2024, ICLR 2025), 분할당 전체 500개 질문, LLM 없음, API 키 없음, 완전히 오프라인으로 실행됩니다. 논문의 공식 flat-bm25 기준선 대비 +8.6pp ~ +13.2pp R@5 향상(동등한 조건 재현 기준). 전체 카테고리별 표, 재현 지침, 논문 비교 세부 사항은 bench/README.md에 있습니다.

왜 필요한가

AI 코딩 세션은 일시적입니다. 세션이 끝나면 세션이 배운 모든 것(아키텍처 결정, 디버깅 통찰, 프로젝트 컨텍스트)이 사라집니다. 다음 세션은 처음부터 다시 시작합니다.

agent-knowledge는 두 가지 상호 보완적인 시스템으로 이 문제를 해결합니다:

1. 지식 베이스 -- 세션과 머신을 넘어 지속되는 구조화된 항목(결정, 워크플로우, 프로젝트 컨텍스트)의 Git 동기화 마크다운 저장소.

2. 세션 검색 -- 모든 코딩 도구의 세션 기록 전체에 대한 TF-IDF 순위 전체 텍스트 검색으로, 에이전트가 어떤 도구를 사용했는지와 관계없이 이전에 무슨 일이 있었는지 회상할 수 있습니다.

Related MCP server: Doclea MCP

지원 도구

모든 주요 AI 코딩 어시스턴트의 세션이 자동으로 검색됩니다. 도구가 설치되어 있으면 해당 세션이 자동으로 나타납니다.

구성 불필요. 추가 세션 루트는 AGENT_KNOWLEDGE_EXTRA_SESSION_ROOTS 환경 변수(쉼표로 구분된 경로)를 통해 추가할 수 있습니다.

기능

• 호스트 독립적 세션 검색 -- 모든 주요 AI 코딩 어시스턴트(Claude Code, Cursor, Codex CLI, Aider, Continue.dev, Cline, OpenCode)에 걸친 통합 검색. 호스트 이름이 구성에 고정되지 않습니다. 어댑터 레지스트리는 시작 시 설치된 호스트 루트를 프로브합니다.

• 하이브리드 검색 -- 의미론적 벡터 유사도와 TF-IDF 키워드 순위의 혼합

• Git 동기화 지식 베이스 -- YAML frontmatter가 있는 마크다운 저장소, 쓰기 시 자동 커밋 및 푸시

• 자동 오래됨 감지 -- knowledge_analyze(action: "stale_by_code_activity")는 각 항목 본문에 언급된 파일 경로를 최근 세션 요약의 filesModified와 교차 참조합니다. 항목이 인용한 식별자(인라인 백틱 + 펜스 블록)가 수정된 파일에 존재하는지 확인하는 기호 존재 정밀도 레이어와 함께 작동합니다. 여전히 존재하면 신뢰도 가중치가 ×0.3으로 감소합니다. evergreen: true 항목은 면제됩니다.

• 검색 공백 추적 -- knowledge_analyze(action: "search_gaps")는 지난 since_days 동안 결과가 없는 쿼리를 토큰-Jaccard 유사도로 그룹화하여 표시합니다. "다음에 어떤 항목을 작성해야 할까?"에 대한 가장 명확한 신호입니다.

• 섹션 우선순위 컨텍스트 패커 -- knowledge(action: "wakeup")는 토큰 예산(기본 800, token_budget 또는 AGENT_KNOWLEDGE_WAKEUP_BUDGET으로 재정의) 내에서 다중 섹션 번들(identity → active_tasks → recent_decisions → known_gotchas → last_session_summary → top_weighted → semantic_fallback)을 조립합니다. 사용되지 않은 섹션 예산은 이후 섹션에 재분배됩니다.

• 점수화 + 게이트 프로모터 -- 세션 통찰은 6-신호 가중 점수기와 세 가지 독립 게이트(minScore, minRecallCount, minUniqueQueries)를 통해 승격됩니다. 백그라운드에서 자동 실행, knowledge_admin(action: "promote")로 요청 시 실행, 또는 npm run bench:promote로 오프라인 벤치마킹 가능. 실행마다 감사 가능한 .dreams/YYYY-MM-DD.md 일기를 생성합니다.

• 플러그형 어댑터 시스템 -- SessionAdapter 인터페이스를 구현하여 새 도구 지원 추가

• 임베딩 -- 로컬(Hugging Face), OpenAI, Claude/Voyage, 또는 Gemini 제공자

• 퍼지 매칭 -- Levenshtein 거리를 사용한 오타 허용 검색

• 6가지 검색 범위 -- 오류, 계획, 구성, 도구, 파일, 결정

• 6가지 MCP 도구 -- 통합된 작업 기반 인터페이스(knowledge, knowledge_search, knowledge_session, knowledge_graph, knowledge_analyze, knowledge_admin)

• Evergreen 항목 -- frontmatter의 evergreen: true는 순위에서 항목의 감쇠를 면제하고 승격 시 추가 전용으로 만듭니다. 대시보드는 이러한 카드에 압정 배지를 렌더링합니다.

• 작성자 속성 -- 선택적 author: <string> frontmatter는 각 카드에 흐린 칩으로 표시됩니다.

• 코드 그래프 해석 -- 코드 구조를 위한 calls, imports, inherits 엣지 유형; 방향성 BFS 순회(outbound/inbound/both); 효율적인 수집을 위한 bulk_link; 재수집 전에 오래된 코드 엣지를 지우는 unlink_by_origin; code: 접두사가 붙은 노드 ID는 코드와 지식을 구분합니다.

• 시간적 지식 그래프 -- 엣지는 valid_from / valid_to 유효 기간을 지원합니다. as_of 쿼리는 특정 시점 스냅샷을 반환합니다. invalidate 작업은 사실을 삭제하지 않고 종료된 것으로 표시합니다.

• 하이브리드 점수 부스트 -- TF-IDF + 의미론적 혼합 위에 고유 명사 및 시간적 근접성 부스트, 최대 +66.7%로 제한, 신호가 없으면 단락.

• 카테고리를 필터가 아닌 부스트로 -- category_mode: "boost"를 선택하면 잘못된 카테고리 추측이 올바른 답을 버리는 대신 순위를 낮춥니다.

• 축어적 세션 인덱싱 -- 메시지별 청크(≥30자)가 벡터 저장소에 임베딩되어 원시 대화를 검색할 수 있습니다. AGENT_KNOWLEDGE_INDEX_VERBATIM=false로 전환 가능.

• 구성 가능한 Git URL -- 런타임 설정을 위한 knowledge_admin(action: "config"), XDG/AppData 위치에 저장.

• 크로스 머신 지속성 -- 지식은 git을 통해 동기화되고, 세션은 각 도구의 로컬 저장소에서 읽습니다.

• 실시간 대시보드 -- localhost:3423에서 탐색, 검색, 관리.

• 비밀 정보 스크러빙 -- API 키, 토큰, 비밀번호, 개인 키가 git 푸시 전에 자동으로 삭제됩니다.

• 지식 그래프 -- 항목 간 관계 엣지(related_to, supersedes, depends_on, contradicts, specializes, part_of, alternative_to, builds_on) 및 BFS 순회.

• 신뢰도/감쇠 점수 -- 항목은 접근 빈도와 최신성으로 점수가 매겨집니다. 후보에서 확립, 검증으로 자동 승격.

• 메모리 통합 -- 쓰기 시 TF-IDF 중복 감지(유사 항목 경고) 및 일괄 중복 스캔을 위한 knowledge_analyze(action: "consolidate").

• 반성 주기 -- knowledge_analyze(action: "reflect")는 연결되지 않은 항목을 표시하고 에이전트가 새 그래프 연결을 식별하도록 구조화된 프롬프트를 생성합니다.

• 쓰기 시 자동 연결 -- 새 항목은 코사인 유사도 > 0.7일 때 상위 3개 유사 기존 항목에 자동으로 연결됩니다.

• 신뢰도 메타데이터 — 항목은 extracted(사용자 작성) 또는 inferred(자동 증류, 0.85× 검색 순위 승수)로 태그됩니다. confidence_score 필드는 모델의 확신도 0-1을 담습니다.

• 지식 분석 -- knowledge_analyze 작업 god_nodes(가장 많이 연결된 항목), bridges(카테고리 간 연결자), gaps(고립된 항목).

• 지식 브리핑 -- knowledge_analyze(action: "brief")는 세션 시작 방향 설정을 위해 캐시된 ~200 토큰 요약(핵심 개념, 활성 프로젝트, 최근 결정, 오래된 항목 및 공백 수)을 반환합니다.

• 엣지 출처 -- 그래프 엣지는 origin(manual, auto-link, distill, reflect)을 추적하여 분석이 사용자 판단과 자동화된 휴리스틱을 구분할 수 있게 합니다.

• 증류의 결정적 사전 추출 -- 세션 요약에는 이제 bash/도구 출력에서 정규식으로 추출된 git 커밋, 오류 패턴, 접근한 URL, 변경된 패키지가 포함됩니다(LLM 비용 없음).

• 모든 검색 결과의 신선도 메타데이터 -- 모든 지식 결과는 freshness: { body_age_days, last_accessed, access_count, verified_at, verification_age_days, evergreen }를 담습니다. 에이전트는 신뢰 신호를 읽고 결정합니다. 우리는 정책적 순위 하향을 부과하지 않습니다.

• 카테고리별 감쇠 기간 -- "Unused" 필터와 bytype 차트는 카테고리별 임계값(프로젝트 180일, 사람 365일, 결정 90일, 워크플로우 60일, 메모 30일)을 존중하므로 정체성 관련 콘텐츠가 매주 다시 읽히지 않는다고 해서 오래된 것처럼 보이지 않습니다.

• 수명 주기 훅 -- SessionStart 자동 웨이크업 + 수집 신선도 검사, UserPromptSubmit 첫 프롬프트 타겟 주입, PreCompact 메모리 플러시 알림 + 증류, SessionEnd 증류. 총 6개의 훅 스크립트, 모두 실패 시 열림, 각각 AGENT_KNOWLEDGE_* 환경 변수로 전환 가능. docs/HOOKS.md 참조.

• 호스트 자동 메모리 대체 -- 세션별 메모리 시스템이 있는 호스트(Claude Code의 ~/.claude/projects/*/memory/, 다른 IDE에서도 유사)에서 지속적인 사용자 사실과 피드백을 agent-knowledge로 라우팅합니다. 자동 메모리는 머신 로컬이며 다른 머신에 보이지 않습니다. agent-knowledge는 git 동기화, 크로스 머신, 검색 가능하며 웨이크업에 표시됩니다. Claude Code 통합 참고 사항은 docs/USER-MANUAL.md를 참조하세요.

코드베이스 수집

knowledge-ingest 스킬은 코드베이스 디렉토리에서 지식 베이스를 채우거나 업데이트합니다. tree-sitter를 사용하여 토큰 없는 구조적 추출(클래스, 함수, 가져오기, 호출 그래프, 근거 주석)을 수행한 다음 파일을 하위 시스템으로 클러스터링하고 기존 MCP 도구를 통해 지식 항목 + 그래프 엣지를 생성합니다. 이후 실행은 증분적입니다. 변경된 파일만 다시 처리됩니다.

/knowledge-ingest ./my-project

Agent Skills 표준을 사용합니다. Claude Code, OpenCode, Cursor, Codex CLI, Gemini CLI와 호환됩니다. 자세한 내용은 수집 가이드를 참조하세요.

지원 언어: TypeScript, JavaScript, Python, Go, Rust, Java, C, C++.

빠른 시작

npm에서 설치

npm install -g agent-knowledge

또는 소스에서 클론

git clone https://github.com/keshrath/agent-knowledge.git
cd agent-knowledge
npm install && npm run build

옵션 1: MCP 서버 (AI 에이전트용)

MCP 클라이언트 구성(Claude Code, Cline 등)에 추가:

{
  "mcpServers": {
    "agent-knowledge": {
      "command": "npx",
      "args": ["agent-knowledge"]
    }
  }
}

대시보드는 첫 MCP 연결 시 http://localhost:3423에서 자동으로 시작됩니다.

클라이언트별 지침(Claude Code, Cursor, Windsurf, OpenCode)은 설정 가이드를 참조하세요.

옵션 2: 독립형 서버 (REST/WebSocket 클라이언트용)

node dist/server.js --port 3423

MCP 도구 (6)

지식 베이스

검색

응답 형태: {mode: "general" | "scoped", sessions, knowledge}. 범위 모드는 설계상 knowledge: []를 반환합니다.

범위: errors, plans, configs, tools, files, decisions, all.

검색 조정 옵션:

• mmr: true는 MMR(Maximal Marginal Relevance) 재순위화를 적용합니다(상위 K에서 거의 중복된 클러스터 제거). mmr_lambda 0-1, 기본값 0.7.

• category_mode: "boost"(기본값)는 일치하지 않는 항목을 제외하는 대신 일치하는 카테고리 항목에 1.25배 점수 배율을 적용합니다. 하드 필터 동작을 원하면 "filter"를 전달하세요.

• explain: true는 모든 지식 검색 결과에 score_components: {bm25, decay, maturity, confidence, category_boost, mmr_penalty}를 첨부합니다.

세션

지식 그래프

지식 유형: related_to, supersedes, depends_on, contradicts, specializes, part_of, alternative_to, builds_on 코드 구조 유형: calls, imports, inherits

탐색 방향: outbound (source→target), inbound (target→source), both (기본값, 무방향)

분석

관리

점수 기반 승격기

모든 프로젝트 수준 후보는 여섯 가지 신호(관련성 0.30, 빈도 0.24, 쿼리 다양성 0.15, 최신성 0.15, 통합 0.10, 개념적 풍부성 0.06)로 점수가 매겨지며 minScore ≥ 0.5, minRecallCount ≥ 2, minUniqueQueries ≥ 2 게이트가 적용됩니다. 세 게이트 모두 통과해야 합니다. 백그라운드 자동 승격은 동일한 auto_distill 구성 플래그로 제어되며, knowledge_admin(action: "promote")로 필요 시 호출할 수 있습니다.

• promote_mode: "explain"(기본값) — 후보 점수 산정 + 게이트 적용, 일기 작성, KB는 변경하지 않음.

• promote_mode: "apply" — 통과한 후보 승격, 일기 작성, git 커밋.

• 실행할 때마다 ~/agent-knowledge/.dreams/YYYY-MM-DD.md에 후보별 신호 분석과 게이트 결과를 기록합니다. . 접두사 디렉터리는 git 추적되지만 목록/검색에서 제외됩니다.

• 근거 기반 재수화: 소스 세션 파일이 디스크에 더 이상 없으면 후보를 건너뜁니다(삭제된 콘텐츠 승격 방지).

• evergreen: true 프론트매터가 있는 항목은 승격으로 덮어쓰지 않으며, 활동이 추가됩니다.

쓰기 벤치 하네스: npm run bench:promote — "이후 세션에서 참조됨" 자동 라벨링을 통한 오프라인 재생. 게이트 적용 승격기를 단순 "모두 배포" 기준선과 비교하여 정밀도/재현율/F1을 보고합니다. 신호 가중치나 임계값 변경을 배포하기 전에 이를 사용하여 검증하세요.

REST API

아키텍처

graph LR
    subgraph Storage
        KB[(Knowledge Base<br/>~/agent-knowledge<br/>Git Repository)]
    end

    subgraph Session Sources
        CC[(Claude Code<br/>JSONL)]
        CU[(Cursor<br/>JSONL)]
        OC[(OpenCode<br/>SQLite)]
        CL[(Cline<br/>JSON)]
        CD[(Continue.dev<br/>JSON)]
        AI[(Aider<br/>MD / JSONL)]
    end

    subgraph agent-knowledge
        KM[Knowledge Module<br/>store / search / git]
        AD[Session Adapters<br/>auto-discovery]
        SE[Search Engine<br/>TF-IDF + Fuzzy]
        DS[Dashboard<br/>:3423]
        MCP[MCP Server<br/>stdio]
    end

    subgraph Clients
        AG[Agent Sessions]
        WB[Web Browser]
    end

    KB <-->|git pull/push| KM
    CC --> AD
    CU --> AD
    OC --> AD
    CL --> AD
    CD --> AD
    AI --> AD
    AD --> SE
    KM --> MCP
    SE --> MCP
    KM --> DS
    SE --> DS
    MCP --> AG
    DS --> WB

지식 그래프

항목과 코드 심볼은 전용 edges SQLite 테이블에 저장된 유형 지정, 가중치 적용 엣지를 통해 연결될 수 있습니다. 11가지 관계 유형이 지원됩니다 — 지식 엣지용 8개와 코드 구조용 3개:

지식: related_to, supersedes, depends_on, contradicts, specializes, part_of, alternative_to, builds_on 코드 구조: calls, imports, inherits

• knowledge_graph(action: "link") 엣지 생성 또는 업데이트 (선택적 strength 0-1)

• knowledge_graph(action: "unlink") 엣지 제거 (유형별 선택 필터링)

• knowledge_graph(action: "list") 항목 또는 관계 유형별 엣지 나열

• knowledge_graph(action: "traverse") 시작 항목에서 방향성 BFS 탐색 수행. direction (outbound, inbound, both) 및 rel_type 필터 지원

• knowledge_graph(action: "bulk_link") 단일 트랜잭션에서 엣지 일괄 생성 (코드 그래프 수집용)

• knowledge_graph(action: "unlink_by_origin") 특정 origin을 가진 모든 엣지 삭제 (재수집 전 오래된 코드 엣지 정리용)

코드 그래프

코드 구조 엣지는 코드베이스 수집 중 knowledge-ingest 스킬에 의해 생성됩니다. code: 접두사 노드 ID를 사용합니다:

code:src/auth/middleware.ts                    # file node
code:src/auth/middleware.ts::validateToken      # symbol node

쿼리 예시:

# Who calls validateToken?
knowledge_graph({ action: "traverse", entry: "code:src/auth.ts::validateToken", direction: "inbound", rel_type: "calls", depth: 3 })

# What breaks if I change this function?
knowledge_graph({ action: "traverse", entry: "code:src/auth.ts::validateToken", direction: "inbound", rel_type: "calls", depth: 5 })

# Combined: callers + knowledge context (decisions, design rationale)
knowledge_graph({ action: "traverse", entry: "code:src/auth.ts::validateToken", depth: 2 })

자동 링크

knowledge의 action: "write"가 항목을 생성하거나 업데이트할 때, 코사인 유사도를 통해 기존 항목 중 상위 3개의 가장 유사한 항목을 자동으로 찾고 0.7 이상의 점수를 받은 모든 쌍에 대해 related_to 엣지를 생성합니다.

신뢰도 및 감쇠 점수

각 지식 항목은 entry_scores SQLite 테이블에 추적되는 신뢰도 점수를 가집니다. 검색 결과는 다음을 사용하여 순위가 매겨집니다:

finalScore = baseRelevance * 0.5^(daysSinceLastAccess / 90) * maturityMultiplier

항목은 접근 횟수에 따라 자동으로 성숙합니다:

자주 접근되는 항목은 검색 순위가 올라가고, 오래된 항목은 시간이 지나면서 가치가 감소합니다.

검색 기능

TF-IDF 랭킹 -- 결과는 단어 빈도-역문서 빈도(term frequency-inverse document frequency)로 점수가 매겨집니다. 희귀한 용어일수록 관련성이 높아집니다. 전역 인덱스는 60초 동안 캐시됩니다.

퍼지 매칭 -- 슬라이딩 윈도우를 사용한 Levenshtein 편집 거리. 임계값을 구성할 수 있습니다(기본값 0.7).

범위 지정 검색 -- knowledge_search의 scope 매개변수를 통해 제공됩니다:

통합

REST 쓰기 엔드포인트

POST /api/knowledge는 { category, filename, content }를 받아 전체 쓰기 파이프라인을 실행합니다: git pull → 파일 쓰기 → 임베딩 인덱스 → 자동 링크 → git push → 중복 확인. 상태 코드 201과 함께 { path, autoLinks?, duplicateWarnings?, git }를 반환합니다.

이를 통해 MCP 연결 없이도 다른 서비스에서 HTTP 기반 쓰기가 가능합니다.

agent-tasks KnowledgeBridge

agent-tasks에는 작업 완료 시 learning 및 decision 아티팩트를 agent-knowledge로 자동 푸시하는 내장 KnowledgeBridge가 있습니다. 항목은 frontmatter 태그(agent-tasks, 프로젝트 이름, 아티팩트 유형)와 함께 decisions/에 저장되고, 임베딩으로 자동 인덱싱되며 유사한 항목에 자동 링크됩니다. 구성이 필요 없습니다 — agent-knowledge가 localhost:3423에서 실행 중이면 작동합니다.

테스트

npm test              # 563 tests across 35 files
npm run test:watch    # Watch mode
npm run lint          # ESLint on src/ and tests/
npm run typecheck     # tsc --noEmit
npm run check         # typecheck + lint + format + test

환경 변수

모든 환경 변수는 AGENT_KNOWLEDGE_* 접두사 아래에 있습니다. 호스트 이름이 하드코딩되어 있지 않습니다 — 어댑터 레지스트리는 구성 없이 설치된 AI 코딩 호스트(.claude, .cursor, .codex, .aider, .continue, OpenCode)를 자동 감지합니다.

핵심

임베딩

API 키

프로젝트 범위 재정의가 표준 키보다 우선합니다. 둘 중 하나를 설정하세요. 범위 지정 형식을 사용하면 나머지 환경과 다른 키로 agent-knowledge를 실행할 수 있습니다.

훅

외부 도구 재정의

문서

• 설정 가이드 — 설치, 클라이언트 설정(Claude Code, OpenCode, Cursor, Windsurf), 훅, 스킬

• 수집 가이드 — 코드베이스 수집 스킬, tree-sitter 추출, 증분 업데이트

• 아키텍처 — 소스 구조, 설계 원칙, 데이터베이스 스키마

• 대시보드 — 웹 UI 뷰 및 기능

• 변경 로그

라이선스

MIT