Agent Knowledge

agent-knowledge

[License: MIT] [Node >= 20] [Tests: 604 passing] [MCP Tools: 6] [LongMemEval R@5: 98.8%]

Cross-session memory and recall for AI coding assistants -- works with Claude Code, Cursor, OpenCode, Cline, Continue.dev, and Aider out of the box. Git-synced knowledge base, hybrid semantic+TF-IDF search, auto-distillation with secrets scrubbing.

Benchmark: R@5 = 97.2% (sparse) / 98.8% (hybrid) on longmemeval_s and 86.0% (sparse) / 88.4% (hybrid) on the harder longmemeval_m split — the public LongMemEval academic benchmark (Wu et al. 2024, ICLR 2025), full 500 questions per split, no LLM, no API key, runs entirely offline. +8.6pp to +13.2pp R@5 over the paper's official flat-bm25 baseline in apples-to-apples reproduction. Full per-category table, reproduction instructions, and paper-comparison details in bench/README.md.

In Claude Code, the agent-knowledge plugin adds the /knowledge pane: the knowledge base beside the conversation. How it works, with pictures: the user manual.

[The /knowledge pane: open it, open an entry, follow a link]

Why

AI coding sessions are ephemeral. When a session ends, everything it learned -- architecture decisions, debugging insights, project context -- is gone. The next session starts from scratch.

agent-knowledge solves this with two complementary systems:

1. Knowledge Base -- a git-synced markdown vault of structured entries (decisions, workflows, project context) that persists across sessions and machines.
2. Session Search -- TF-IDF ranked full-text search across session transcripts from all your coding tools, so agents can recall what happened before -- regardless of which tool was used.

Supported Tools

Sessions from all major AI coding assistants are auto-discovered -- if a tool is installed, its sessions appear automatically.

No configuration needed. Additional session roots can be added via the AGENT_KNOWLEDGE_EXTRA_SESSION_ROOTS env var (comma-separated paths).

Features

• Host-agnostic session search -- unified search across every major AI coding assistant (Claude Code, Cursor, Codex CLI, Aider, Continue.dev, Cline, OpenCode). No host name is baked into configuration — the adapter registry probes installed host roots at startup.
• Hybrid search -- semantic vector similarity blended with TF-IDF keyword ranking
• Git-synced knowledge base -- markdown vault with YAML frontmatter, auto commit and push on writes
• Automatic staleness detection -- knowledge_analyze(action: "stale_by_code_activity") cross-references file paths mentioned in each entry body against filesModified in recent session summaries. Pairs with a symbol-presence precision layer: identifiers the entry quotes (inline backticks + fenced blocks) are checked in the touched file; if they still exist, confidence downweights ×0.3. Entries with evergreen: true are exempt.
• Search-gap tracking -- knowledge_analyze(action: "search_gaps") surfaces zero-result queries over the last since_days, grouped by token-Jaccard similarity. The clearest signal for "what entries should I write next?".
• Section-priority context packer -- knowledge(action: "wakeup") assembles a multi-section bundle (identity → active_tasks → recent_decisions → known_gotchas → last_session_summary → top_weighted → semantic_fallback) within a token budget (default 800, override via token_budget or AGENT_KNOWLEDGE_WAKEUP_BUDGET). Unused section budget redistributes to later sections.
• Scored + gated promoter -- session insights promoted via a 6-signal weighted scorer with three independent gates (minScore, minRecallCount, minUniqueQueries). Runs automatically in background, on demand via knowledge_admin(action: "promote"), or benchable offline via npm run bench:promote. Emits an auditable .dreams/YYYY-MM-DD.md diary every run.
• Pluggable adapter system -- add support for new tools by implementing the SessionAdapter interface
• Embeddings -- local (Hugging Face), OpenAI, Claude/Voyage, or Gemini providers
• Fuzzy matching -- typo-tolerant search using Levenshtein distance
• 6 search scopes -- errors, plans, configs, tools, files, decisions
• 6 MCP tools -- consolidated action-based interface (knowledge, knowledge_search, knowledge_session, knowledge_graph, knowledge_analyze, knowledge_admin)
• Evergreen entries -- evergreen: true in frontmatter exempts an entry from decay in ranking AND makes it append-only under promotion. The /knowledge pane marks them.
• Author attribution -- optional author: <string> frontmatter, kept with the entry and returned by the REST API.
• Code graph resolution -- calls, imports, inherits edge types for code structure; directed BFS traversal (outbound/inbound/both); bulk_link for efficient ingestion; unlink_by_origin for clearing stale code edges before re-ingest; code: prefixed node IDs distinguish code from knowledge
• Temporal knowledge graph -- edges support valid_from / valid_to validity windows; as_of queries return point-in-time snapshots; invalidate action marks facts as ended without deleting them
• Hybrid scoring boosts -- proper-noun and temporal-proximity boosts on top of TF-IDF + semantic blend, capped at +66.7%, short-circuit when no signals are present
• Category as boost (not filter) -- opt into category_mode: "boost" so a wrong category guess down-ranks instead of discarding the right answer
• Verbatim session indexing -- per-message chunks (≥30 chars) embedded into the vector store so raw conversation is retrievable; toggle with AGENT_KNOWLEDGE_INDEX_VERBATIM=false
• Configurable git URL -- knowledge_admin(action: "config") for runtime setup, persisted at XDG/AppData location
• Cross-machine persistence -- knowledge syncs via git, sessions read from local storage of each tool
• /knowledge pane in Claude Code -- browse and search the knowledge base beside the conversation (agent-knowledge plugin)
• Secrets scrubbing -- API keys, tokens, passwords, private keys automatically redacted before git push
• Knowledge graph -- relationship edges between entries (related_to, supersedes, depends_on, contradicts, specializes, part_of, alternative_to, builds_on) with BFS traversal
• Confidence/decay scoring -- entries scored by access frequency and recency; auto-promotion from candidate to established to proven
• Memory consolidation -- TF-IDF duplicate detection on write (warns of similar entries) plus knowledge_analyze(action: "consolidate") for batch dedup scanning
• Reflection cycle -- knowledge_analyze(action: "reflect") surfaces unconnected entries and generates structured prompts for the agent to identify new graph connections
• Auto-linking on write -- new entries automatically linked to top-3 similar existing entries when cosine similarity > 0.7
• Confidence metadata — entries tagged extracted (user-written) or inferred (auto-distilled, 0.85× search rank multiplier); confidence_score field carries the model's certainty 0-1
• Knowledge analysis — knowledge_analyze actions god_nodes (most-connected entries), bridges (cross-category connectors), gaps (isolated entries)
• Knowledge brief — knowledge_analyze(action: "brief") returns a cached ~200 token summary (core concepts, active projects, recent decisions, stale and gap counts) for session-start orientation
• Edge provenance — graph edges track origin (manual, auto-link, distill, reflect) so analysis can distinguish user judgment from automated heuristics
• Deterministic pre-extraction in distillation — session summaries now include git commits, error patterns, URLs accessed, and packages changed extracted via regex from bash/tool output (no LLM cost)
• Freshness metadata on every search hit — every knowledge result carries freshness: { body_age_days, last_accessed, access_count, verified_at, verification_age_days, evergreen }. Agent reads the trust signal and decides; we impose no policy demotion.
• Per-category decay windows — the "Unused" filter and bytype chart honor per-category thresholds (projects 180d, people 365d, decisions 90d, workflows 60d, notes 30d) so identity-shaped content doesn't look stale just because it isn't re-read weekly.
• Lifecycle hooks — SessionStart auto-wakeup + ingest-freshness check, UserPromptSubmit first-prompt targeted injection, PreCompact memory-flush nudge + distill, SessionEnd distill. Six hook scripts total, all fail-open, each toggleable via an AGENT_KNOWLEDGE_* env var. See docs/HOOKS.md.
• Replaces host auto-memory — on hosts with a per-session memory system (Claude Code's ~/.claude/projects/*/memory/, similar in other IDEs), route durable user facts and feedback to agent-knowledge instead. Auto-memory is machine-local and invisible to other machines; agent-knowledge is git-synced, cross-machine, searchable, and surfaces in wakeup. See the Claude Code integration note in docs/USER-MANUAL.md.

Codebase Ingestion

The knowledge-ingest skill populates or updates the knowledge base from a codebase directory. It uses tree-sitter for zero-token structural extraction (classes, functions, imports, call graphs, rationale comments), then clusters files into subsystems and creates knowledge entries + graph edges via existing MCP tools. Subsequent runs are incremental — only changed files are reprocessed.

/knowledge-ingest ./my-project

Uses the Agent Skills standard — works with Claude Code, OpenCode, Cursor, Codex CLI, and Gemini CLI. See Ingestion Guide for details.

Supported languages: TypeScript, JavaScript, Python, Go, Rust, Java, C, C++.

Quick Start

Install from npm

npm install -g agent-knowledge

Or clone from source

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

Option 1: MCP server (for AI agents)

Add to your MCP client config (Claude Code, Cline, etc.):

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

The first MCP process also serves a local REST API on 127.0.0.1:3423 (what the hooks, the /knowledge pane and agent-tasks call); when it exits, another running session takes the port over.

See Setup Guide for client-specific instructions (Claude Code, Cursor, Windsurf, OpenCode).

Option 2: Claude Code plugin

claude plugin marketplace add keshrath/agent-knowledgeclaude plugin install agent-knowledge@agent-knowledge

The plugin brings the MCP server, the knowledge-ingest skill and the /knowledge pane (Claude Code 2.1.289+).

MCP Tools (6)

Knowledge Base

Search

Response shape: {mode: "general" | "scoped", sessions, knowledge}. Scoped mode returns knowledge: [] by design.

Scopes: errors, plans, configs, tools, files, decisions, all.

Search knobs:

• mmr: true applies Maximal Marginal Relevance re-ranking (kills near-duplicate clusters in top-K). mmr_lambda 0-1, default 0.7.
• category_mode: "boost" (default) gives matching-category entries a 1.25× score multiplier instead of dropping non-matches. Pass "filter" for hard-filter behavior.
• explain: true attaches score_components: {bm25, decay, maturity, confidence, category_boost, mmr_penalty} to every knowledge hit.

Sessions

Knowledge Graph

Knowledge types: related_to, supersedes, depends_on, contradicts, specializes, part_of, alternative_to, builds_on Code structure types: calls, imports, inherits

Traverse directions: outbound (source→target), inbound (target→source), both (default, undirected)

Analysis

Admin

Scored promoter

Every project-level candidate is scored on six signals (relevance 0.30, frequency 0.24, query-diversity 0.15, recency 0.15, consolidation 0.10, conceptual-richness 0.06) and gated on minScore ≥ 0.5, minRecallCount ≥ 2, minUniqueQueries ≥ 2. All three gates must pass. Background auto-promotion is controlled by the same auto_distill config flag; invoke on demand with knowledge_admin(action: "promote").

• promote_mode: "explain" (default) — score + gate candidates, write diary, DO NOT touch the KB.
• promote_mode: "apply" — promote candidates that pass, write diary, git-commit.
• Every run drops ~/agent-knowledge/.dreams/YYYY-MM-DD.md with per-candidate signal breakdowns and gate outcomes. The .-prefixed dir is git-tracked but excluded from list/search.
• Grounded rehydration: a candidate is skipped if its source session file no longer exists on disk (prevents promoting deleted content).
• Entries with evergreen: true frontmatter are never overwritten by promotion — activity is appended.

Write-bench harness: npm run bench:promote — offline replay with auto-labeling by "referenced in later sessions". Compares gated promoter to a naive "ship all" baseline, reports precision / recall / F1. Use it to gate signal-weight or threshold changes before rolling them out.

REST API

Loopback only (127.0.0.1), JSON only. Every request goes through a guard: a foreign Host or any Origin header gets 403, a request body must be application/json. A :path with a slash is sent encoded (notes%2Fx.md).

Architecture

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[REST API<br/>127.0.0.1:3423]        MCP[MCP Server<br/>stdio]    end
    subgraph Clients        AG[Agent Sessions]        PN["/knowledge pane<br/>hooks, agent-tasks"]    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 --> PN

Knowledge Graph

Entries and code symbols can be connected via typed, weighted edges stored in a dedicated edges SQLite table. Eleven relationship types are supported — 8 for knowledge edges and 3 for code structure:

Knowledge: related_to, supersedes, depends_on, contradicts, specializes, part_of, alternative_to, builds_on Code structure: calls, imports, inherits

• knowledge_graph(action: "link") creates or updates an edge (with optional strength 0-1)
• knowledge_graph(action: "unlink") removes edges (optionally filtered by type)
• knowledge_graph(action: "list") lists edges for an entry or relationship type
• knowledge_graph(action: "traverse") performs directed BFS traversal from a starting entry. Supports direction (outbound, inbound, both) and rel_type filter
• knowledge_graph(action: "bulk_link") batch-creates edges in a single transaction (for code graph ingestion)
• knowledge_graph(action: "unlink_by_origin") deletes all edges with a specific origin (for clearing stale code edges before re-ingest)

Code Graph

Code structure edges are created by the knowledge-ingest skill during codebase ingestion. They use code: prefixed node IDs:

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

Query examples:

# 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 })

Auto-linking

When knowledge with action: "write" creates or updates an entry, it automatically finds the top-3 most similar existing entries via cosine similarity and creates related_to edges for any pair scoring above 0.7.

Confidence & Decay Scoring

Each knowledge entry has a confidence score tracked in the entry_scores SQLite table. Search results are ranked using:

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

Entries mature automatically based on access count:

Frequently accessed entries rise in search rankings; stale entries decay over time.

Search Capabilities

TF-IDF Ranking -- results scored by term frequency-inverse document frequency. Rare terms boost relevance. Global index cached for 60 seconds.

Fuzzy Matching -- Levenshtein edit distance with sliding window. Configurable threshold (default 0.7).

Scoped Recall via knowledge_search with the scope parameter:

Integrations

REST Write Endpoint

POST /api/knowledge accepts { category, filename, content } and runs the full write pipeline: git pull → file write → embedding index → auto-link → git push → duplicate check. Returns { path, autoLinks?, duplicateWarnings?, git } with status 201.

This enables HTTP-based writes from other services without an MCP connection.

agent-tasks KnowledgeBridge

agent-tasks has a built-in KnowledgeBridge that auto-pushes learning and decision artifacts to agent-knowledge on task completion. Entries land in decisions/ with frontmatter tags (agent-tasks, project name, artifact type), are auto-indexed with embeddings, and auto-linked to similar entries. No configuration needed: while any session runs agent-knowledge, its REST API on 127.0.0.1:3423 answers.

Testing

npm test              # 604 tests across 39 filesnpm run test:watch    # Watch modenpm run lint          # ESLint on src/ and tests/npm run typecheck     # tsc --noEmitnpm run check         # typecheck + lint + format + test

Environment Variables

All env vars live under the AGENT_KNOWLEDGE_* prefix. No host name is baked in — the adapter registry auto-detects installed AI coding hosts (.claude, .cursor, .codex, .aider, .continue, OpenCode) without configuration.

Core

Embeddings

API keys

Project-scoped overrides win over the standard keys. Set either; the scoped form lets you run agent-knowledge with a different key than the rest of your environment.

Hooks

External tool overrides

Documentation

• Setup Guide — installation, client setup (Claude Code, OpenCode, Cursor, Windsurf), hooks, skills
• Ingestion Guide — codebase ingestion skill, tree-sitter extraction, incremental updates
• Architecture — source structure, design principles, database schema
• Hooks — the Claude Code lifecycle hooks
• Changelog

License

MIT