{
"markdown": "# agent-knowledge\n\n[](LICENSE)\n[](https://nodejs.org)\n[]()\n[]()\n[]()\n\n**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.\n\n**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`](bench/README.md).\n\n
\n
\n
\n
\n
\n
\n
Knowledge base with category filtering
\n
TF-IDF ranked session search
\n
\n
\n\n## Why\n\nAI 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.\n\n**agent-knowledge** solves this with two complementary systems:\n\n1. **Knowledge Base** -- a git-synced markdown vault of structured entries (decisions, workflows, project context) that persists across sessions and machines.\n2. **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.\n\n## Supported Tools\n\nSessions from all major AI coding assistants are auto-discovered -- if a tool is installed, its sessions appear automatically.\n\n| Tool | Format | Auto-detected path |\n| ---------------- | -------------- | --------------------------------------------------------------- |\n| **Claude Code** | JSONL | `~/.claude/projects/` |\n| **Cursor** | JSONL | `~/.cursor/projects/*/agent-transcripts/` |\n| **Codex CLI** | JSONL | `~/.codex/projects/` |\n| **Aider** | Markdown/JSONL | `.aider.chat.history.md` / `.aider.llm.history` in project dirs |\n| **Continue.dev** | JSON | `~/.continue/projects/` |\n| **Cline** | JSON | VS Code globalStorage `saoudrizwan.claude-dev/tasks/` |\n| **OpenCode** | SQLite | `~/.local/share/opencode/opencode.db` (or `$OPENCODE_DATA_DIR`) |\n\nNo configuration needed. Additional session roots can be added via the `AGENT_KNOWLEDGE_EXTRA_SESSION_ROOTS` env var (comma-separated paths).\n\n## Features\n\n- **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.\n- **Hybrid search** -- semantic vector similarity blended with TF-IDF keyword ranking\n- **Git-synced knowledge base** -- markdown vault with YAML frontmatter, auto commit and push on writes\n- **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.\n- **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?\".\n- **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.\n- **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.\n- **Pluggable adapter system** -- add support for new tools by implementing the `SessionAdapter` interface\n- **Embeddings** -- local (Hugging Face), OpenAI, Claude/Voyage, or Gemini providers\n- **Fuzzy matching** -- typo-tolerant search using Levenshtein distance\n- **6 search scopes** -- errors, plans, configs, tools, files, decisions\n- **6 MCP tools** -- consolidated action-based interface (`knowledge`, `knowledge_search`, `knowledge_session`, `knowledge_graph`, `knowledge_analyze`, `knowledge_admin`)\n- **Evergreen entries** -- `evergreen: true` in frontmatter exempts an entry from decay in ranking AND makes it append-only under promotion. Dashboard renders a push-pin badge on these cards.\n- **Author attribution** -- optional `author: ` frontmatter surfaces as a muted chip on each card.\n- **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\n- **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\n- **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\n- **Category as boost (not filter)** -- opt into `category_mode: \"boost\"` so a wrong category guess down-ranks instead of discarding the right answer\n- **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`\n- **Configurable git URL** -- `knowledge_admin(action: \"config\")` for runtime setup, persisted at XDG/AppData location\n- **Cross-machine persistence** -- knowledge syncs via git, sessions read from local storage of each tool\n- **Real-time dashboard** -- browse, search, and manage at `localhost:3423`\n- **Secrets scrubbing** -- API keys, tokens, passwords, private keys automatically redacted before git push\n- **Knowledge graph** -- relationship edges between entries (related_to, supersedes, depends_on, contradicts, specializes, part_of, alternative_to, builds_on) with BFS traversal\n- **Confidence/decay scoring** -- entries scored by access frequency and recency; auto-promotion from candidate to established to proven\n- **Memory consolidation** -- TF-IDF duplicate detection on write (warns of similar entries) plus `knowledge_analyze(action: \"consolidate\")` for batch dedup scanning\n- **Reflection cycle** -- `knowledge_analyze(action: \"reflect\")` surfaces unconnected entries and generates structured prompts for the agent to identify new graph connections\n- **Auto-linking on write** -- new entries automatically linked to top-3 similar existing entries when cosine similarity > 0.7\n- **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\n- **Knowledge analysis** — `knowledge_analyze` actions `god_nodes` (most-connected entries), `bridges` (cross-category connectors), `gaps` (isolated entries)\n- **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\n- **Edge provenance** — graph edges track `origin` (manual, auto-link, distill, reflect) so analysis can distinguish user judgment from automated heuristics\n- **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)\n- **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.\n- **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.\n- **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`](docs/HOOKS.md).\n- **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`](docs/USER-MANUAL.md#persistent-memory--agent-knowledge-not-host-auto-memory).\n\n## Codebase Ingestion\n\nThe **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.\n\n```\n/knowledge-ingest ./my-project\n```\n\nUses the [Agent Skills standard](https://agentskills.io) — works with Claude Code, OpenCode, Cursor, Codex CLI, and Gemini CLI. See [Ingestion Guide](docs/INGEST.md) for details.\n\n**Supported languages:** TypeScript, JavaScript, Python, Go, Rust, Java, C, C++.\n\n## Quick Start\n\n### Install from npm\n\n```bash\nnpm install -g agent-knowledge\n```\n\n### Or clone from source\n\n```bash\ngit clone https://github.com/keshrath/agent-knowledge.git\ncd agent-knowledge\nnpm install && npm run build\n```\n\n### Option 1: MCP server (for AI agents)\n\nAdd to your MCP client config (Claude Code, Cline, etc.):\n\n```json\n{\n \"mcpServers\": {\n \"agent-knowledge\": {\n \"command\": \"npx\",\n \"args\": [\"agent-knowledge\"]\n }\n }\n}\n```\n\nThe dashboard auto-starts at http://localhost:3423 on the first MCP connection.\n\nSee [Setup Guide](docs/SETUP.md) for client-specific instructions (Claude Code, Cursor, Windsurf, OpenCode).\n\n### Option 2: Standalone server (for REST/WebSocket clients)\n\n```bash\nnode dist/server.js --port 3423\n```\n\n## MCP Tools (6)\n\n### Knowledge Base\n\n| Tool | Action | Description | Parameters |\n| ----------- | -------- | ------------------------------------------------------------- | ------------------------------------------------ |\n| `knowledge` | `list` | List entries by category and/or tag | `category?`, `tag?` |\n| | `read` | Read a specific entry | `path` (required) |\n| | `write` | Create/update entry (auto git sync) | `category`, `filename`, `content` (all required) |\n| | `delete` | Delete an entry (auto git sync) | `path` (required) |\n| | `sync` | Manual git pull + push | -- |\n| | `wakeup` | Return L0 identity + L1 top-weighted entries (token-budgeted) | `token_budget?`, `category?` |\n\n### Search\n\n| Tool | Description | Parameters |\n| ------------------ | --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |\n| `knowledge_search` | General hybrid TF-IDF + semantic (no `scope`) | `query`, `project?`, `role?`, `max_results?`, `ranked?`, `semantic?`, `category?`, `category_mode?`, `mmr?`, `mmr_lambda?`, `explain?` |\n| | Scoped session-only recall (when `scope` set) | `query`, `scope`, `project?`, `max_results?` |\n\nResponse shape: `{mode: \"general\" | \"scoped\", sessions, knowledge}`. Scoped mode returns `knowledge: []` by design.\n\nScopes: `errors`, `plans`, `configs`, `tools`, `files`, `decisions`, `all`.\n\nSearch knobs:\n\n- `mmr: true` applies Maximal Marginal Relevance re-ranking (kills near-duplicate clusters in top-K). `mmr_lambda` 0-1, default 0.7.\n- `category_mode: \"boost\"` (default) gives matching-category entries a 1.25× score multiplier instead of dropping non-matches. Pass `\"filter\"` for hard-filter behavior.\n- `explain: true` attaches `score_components: {bm25, decay, maturity, confidence, category_boost, mmr_penalty}` to every knowledge hit.\n\n### Sessions\n\n| Tool | Action | Description | Parameters |\n| ------------------- | --------- | -------------------------------------- | --------------------------------------------------- |\n| `knowledge_session` | `list` | List sessions with metadata | `project?` |\n| | `get` | Retrieve full session conversation | `session_id`, `project?`, `include_tools?`, `tail?` |\n| | `summary` | Session summary (topics, tools, files) | `session_id`, `project?` |\n\n### Knowledge Graph\n\n| Tool | Action | Description | Parameters |\n| ----------------- | ------------------ | ----------------------------------------- | ----------------------------------------------------------------- |\n| `knowledge_graph` | `link` | Create/update edge between entries | `source`, `target`, `rel_type`, `strength?` |\n| | `unlink` | Remove edges between entries | `source`, `target`, `rel_type?` |\n| | `invalidate` | Mark edges as expired (set valid_to) | `source`, `target`, `rel_type?`, `valid_to?` |\n| | `list` | List edges | `entry?`, `rel_type?`, `as_of?` |\n| | `traverse` | Directed BFS traversal from an entry | `entry`, `depth?`, `direction?`, `rel_type?`, `as_of?` |\n| | `bulk_link` | Batch-create edges (code graph ingestion) | `edges` (array of {source, target, rel_type, strength?, origin?}) |\n| | `unlink_by_origin` | Delete all edges by origin | `origin` |\n\n**Knowledge types**: `related_to`, `supersedes`, `depends_on`, `contradicts`, `specializes`, `part_of`, `alternative_to`, `builds_on`\n**Code structure types**: `calls`, `imports`, `inherits`\n\n**Traverse directions**: `outbound` (source→target), `inbound` (target→source), `both` (default, undirected)\n\n### Analysis\n\n| Tool | Action | Description | Parameters |\n| ------------------- | ------------- | ------------------------------------------ | --------------------------- |\n| `knowledge_analyze` | `consolidate` | Find near-duplicate entries | `category?`, `threshold?` |\n| | `reflect` | Find unconnected entries for linking | `category?`, `max_entries?` |\n| | `god_nodes` | Most-connected entries (degree centrality) | `top_n?` |\n| | `bridges` | Cross-category connectors (betweenness) | `top_n?` |\n| | `gaps` | Isolated entries (0-1 edges) by maturity | `max_entries?` |\n| | `brief` | Cached ~200 token knowledge base summary | -- |\n\n### Admin\n\n| Tool | Action | Description | Parameters |\n| ----------------- | -------------------- | ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |\n| `knowledge_admin` | `status` | Vector store statistics | -- |\n| | `config` | View or update configuration | `git_url?`, `memory_dir?`, `auto_distill?` |\n| | `rebuild_embeddings` | Re-embed all knowledge entries (useful on provider switch) | -- |\n| | `prune_orphans` | Delete embeddings for sessions no longer on disk | `vacuum?`, `force_vacuum?` |\n| | `vacuum` | Reclaim free pages in the vector store | -- |\n| | `promote` | Scored + gated promoter | `promote_mode?` (`apply`\\|`explain`), `min_score?`, `min_recall_count?`, `min_unique_queries?` |\n\n### Scored promoter\n\nEvery 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\")`.\n\n- `promote_mode: \"explain\"` (default) — score + gate candidates, write diary, DO NOT touch the KB.\n- `promote_mode: \"apply\"` — promote candidates that pass, write diary, git-commit.\n- 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.\n- Grounded rehydration: a candidate is skipped if its source session file no longer exists on disk (prevents promoting deleted content).\n- Entries with `evergreen: true` frontmatter are never overwritten by promotion — activity is appended.\n\nWrite-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.\n\n## REST API\n\n| Method | Endpoint | Description |\n| ------ | --------------------------------------- | -------------------------- |\n| GET | `/api/knowledge` | List knowledge entries |\n| GET | `/api/knowledge/search?q=` | Search knowledge base |\n| GET | `/api/knowledge/:path` | Read a specific entry |\n| GET | `/api/knowledge/god-nodes?top_n=` | Most-connected entries |\n| GET | `/api/knowledge/bridges?top_n=` | Cross-category connectors |\n| GET | `/api/knowledge/gaps?max_entries=` | Isolated entries |\n| GET | `/api/knowledge/brief` | Knowledge base brief |\n| GET | `/api/sessions` | List sessions |\n| GET | `/api/sessions/search?q=&role=&ranked=` | Search sessions (TF-IDF) |\n| GET | `/api/sessions/recall?scope=&q=` | Scoped recall |\n| GET | `/api/sessions/:id` | Read a session |\n| GET | `/api/sessions/:id/summary` | Session summary |\n| POST | `/api/knowledge` | Write entry (HTTP clients) |\n| GET | `/health` | Health check |\n\n## Architecture\n\n```mermaid\ngraph LR\n subgraph Storage\n KB[(Knowledge Base ~/agent-knowledge Git Repository)]\n end\n\n subgraph Session Sources\n CC[(Claude Code JSONL)]\n CU[(Cursor JSONL)]\n OC[(OpenCode SQLite)]\n CL[(Cline JSON)]\n CD[(Continue.dev JSON)]\n AI[(Aider MD / JSONL)]\n end\n\n subgraph agent-knowledge\n KM[Knowledge Module store / search / git]\n AD[Session Adapters auto-discovery]\n SE[Search Engine TF-IDF + Fuzzy]\n DS[Dashboard :3423]\n MCP[MCP Server stdio]\n end\n\n subgraph Clients\n AG[Agent Sessions]\n WB[Web Browser]\n end\n\n KB <-->|git pull/push| KM\n CC --> AD\n CU --> AD\n OC --> AD\n CL --> AD\n CD --> AD\n AI --> AD\n AD --> SE\n KM --> MCP\n SE --> MCP\n KM --> DS\n SE --> DS\n MCP --> AG\n DS --> WB\n```\n\n## Knowledge Graph\n\nEntries 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:\n\n**Knowledge**: `related_to`, `supersedes`, `depends_on`, `contradicts`, `specializes`, `part_of`, `alternative_to`, `builds_on`\n**Code structure**: `calls`, `imports`, `inherits`\n\n- **`knowledge_graph(action: \"link\")`** creates or updates an edge (with optional strength 0-1)\n- **`knowledge_graph(action: \"unlink\")`** removes edges (optionally filtered by type)\n- **`knowledge_graph(action: \"list\")`** lists edges for an entry or relationship type\n- **`knowledge_graph(action: \"traverse\")`** performs directed BFS traversal from a starting entry. Supports `direction` (`outbound`, `inbound`, `both`) and `rel_type` filter\n- **`knowledge_graph(action: \"bulk_link\")`** batch-creates edges in a single transaction (for code graph ingestion)\n- **`knowledge_graph(action: \"unlink_by_origin\")`** deletes all edges with a specific origin (for clearing stale code edges before re-ingest)\n\n### Code Graph\n\nCode structure edges are created by the `knowledge-ingest` skill during codebase ingestion. They use `code:` prefixed node IDs:\n\n```\ncode:src/auth/middleware.ts # file node\ncode:src/auth/middleware.ts::validateToken # symbol node\n```\n\nQuery examples:\n\n```\n# Who calls validateToken?\nknowledge_graph({ action: \"traverse\", entry: \"code:src/auth.ts::validateToken\", direction: \"inbound\", rel_type: \"calls\", depth: 3 })\n\n# What breaks if I change this function?\nknowledge_graph({ action: \"traverse\", entry: \"code:src/auth.ts::validateToken\", direction: \"inbound\", rel_type: \"calls\", depth: 5 })\n\n# Combined: callers + knowledge context (decisions, design rationale)\nknowledge_graph({ action: \"traverse\", entry: \"code:src/auth.ts::validateToken\", depth: 2 })\n```\n\n### Auto-linking\n\nWhen `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.\n\n## Confidence & Decay Scoring\n\nEach knowledge entry has a confidence score tracked in the `entry_scores` SQLite table. Search results are ranked using:\n\n```\nfinalScore = baseRelevance * 0.5^(daysSinceLastAccess / 90) * maturityMultiplier\n```\n\nEntries mature automatically based on access count:\n\n| Stage | Accesses | Multiplier |\n| ------------- | -------- | ---------- |\n| `candidate` | < 5 | 0.5x |\n| `established` | 5-19 | 1.0x |\n| `proven` | 20+ | 1.5x |\n\nFrequently accessed entries rise in search rankings; stale entries decay over time.\n\n## Search Capabilities\n\n**TF-IDF Ranking** -- results scored by term frequency-inverse document frequency. Rare terms boost relevance. Global index cached for 60 seconds.\n\n**Fuzzy Matching** -- Levenshtein edit distance with sliding window. Configurable threshold (default 0.7).\n\n**Scoped Recall** via `knowledge_search` with the `scope` parameter:\n\n| Scope | Matches |\n| ----------- | ----------------------------------------- |\n| `errors` | Stack traces, exceptions, failed commands |\n| `plans` | Architecture, TODOs, implementation steps |\n| `configs` | Settings, env vars, configuration files |\n| `tools` | MCP tool calls, CLI commands |\n| `files` | File paths, modifications |\n| `decisions` | Trade-offs, rationale, choices |\n\n## Integrations\n\n### REST Write Endpoint\n\n`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.\n\nThis enables HTTP-based writes from other services without an MCP connection.\n\n### agent-tasks KnowledgeBridge\n\n[agent-tasks](https://github.com/keshrath/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 — if agent-knowledge is running at `localhost:3423`, it works.\n\n## Testing\n\n```bash\nnpm test # 563 tests across 35 files\nnpm run test:watch # Watch mode\nnpm run lint # ESLint on src/ and tests/\nnpm run typecheck # tsc --noEmit\nnpm run check # typecheck + lint + format + test\n```\n\n## Environment Variables\n\nAll 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.\n\n### Core\n\n| Variable | Default | Description |\n| ------------------------------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------- |\n| `AGENT_KNOWLEDGE_MEMORY_DIR` | `~/agent-knowledge` | Git-synced knowledge base directory |\n| `AGENT_KNOWLEDGE_GIT_URL` | -- | Git remote URL (auto-clones if dir missing) |\n| `AGENT_KNOWLEDGE_AUTO_DISTILL` | `true` | Auto-distill session insights into the knowledge base |\n| `AGENT_KNOWLEDGE_INDEX_VERBATIM` | `true` | Index raw session message chunks into the vector store so conversation is retrievable later. Set `false` to save disk at scale. |\n| `AGENT_KNOWLEDGE_DATA_DIR` | (platform config) | Override the primary host data root. Leave unset in the common case — adapters auto-detect every well-known host root under `~/`. |\n| `AGENT_KNOWLEDGE_EXTRA_SESSION_ROOTS` | -- | Extra session directories, comma-separated. Added to whatever auto-detection finds. |\n| `AGENT_KNOWLEDGE_PORT` | `3423` | Dashboard HTTP/WebSocket port |\n\n### Embeddings\n\n| Variable | Default | Description |\n| ---------------------------------------- | ------- | ------------------------------------------------------------------------ |\n| `AGENT_KNOWLEDGE_EMBEDDING_PROVIDER` | `local` | `local` \\| `openai` \\| `claude` \\| `gemini` |\n| `AGENT_KNOWLEDGE_EMBEDDING_ALPHA` | `0.3` | TF-IDF vs semantic blend weight (`0` = pure semantic, `1` = pure TF-IDF) |\n| `AGENT_KNOWLEDGE_EMBEDDING_MODEL` | -- | Override provider default model |\n| `AGENT_KNOWLEDGE_EMBEDDING_IDLE_TIMEOUT` | `60` | Seconds before unloading the local model (`0` = keep loaded) |\n| `AGENT_KNOWLEDGE_EMBEDDING_THREADS` | (auto) | ONNX / OMP thread count for the local provider |\n\n### API keys\n\nProject-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.\n\n| Variable | Fallback | Description |\n| ----------------------------------- | ------------------- | -------------------------- |\n| `AGENT_KNOWLEDGE_OPENAI_API_KEY` | `OPENAI_API_KEY` | OpenAI embeddings |\n| `AGENT_KNOWLEDGE_ANTHROPIC_API_KEY` | `ANTHROPIC_API_KEY` | Claude / Voyage embeddings |\n| `AGENT_KNOWLEDGE_GEMINI_API_KEY` | `GEMINI_API_KEY` | Gemini embeddings |\n\n### Hooks\n\n| Variable | Default | Description |\n| -------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `AGENT_KNOWLEDGE_AUTOWAKE` | `1` | Auto-inject a `knowledge(action: wakeup)` bundle into `SessionStart`. Set `0` to disable. |\n| `AGENT_KNOWLEDGE_WAKEUP_BUDGET` | `800` | Tokens for the wakeup bundle |\n| `AGENT_KNOWLEDGE_FIRSTPROMPT_INJECT` | `1` | Run a targeted `knowledge_search` on the first user prompt and inject top hits. `0` / `false` / `off` to disable. |\n| `AGENT_KNOWLEDGE_FIRSTPROMPT_BUDGET` | `600` | Tokens for first-prompt injection (clamp `[100, 8000]`) |\n| `AGENT_KNOWLEDGE_FIRSTPROMPT_MAX_HITS` | `4` | Max knowledge hits attached to the first prompt (clamp `[1, 20]`) |\n| `AGENT_KNOWLEDGE_PRECOMPACT_NUDGE` | `1` | Before pre-compaction, nudge the agent to save context via `knowledge(action: write)`. `0` disables the nudge; `off` suppresses both nudge and disk dump. |\n\n### External tool overrides\n\n| Variable | Default | Description |\n| ------------------- | ------------------------- | --------------------------------------------------------------------------------------- |\n| `OPENCODE_DATA_DIR` | `~/.local/share/opencode` | Override where OpenCode's session DB lives (OpenCode's own env, honored by our adapter) |\n\n## Documentation\n\n- [Setup Guide](docs/SETUP.md) — installation, client setup (Claude Code, OpenCode, Cursor, Windsurf), hooks, skills\n- [Ingestion Guide](docs/INGEST.md) — codebase ingestion skill, tree-sitter extraction, incremental updates\n- [Architecture](docs/ARCHITECTURE.md) — source structure, design principles, database schema\n- [Dashboard](docs/DASHBOARD.md) — web UI views and features\n- [Changelog](CHANGELOG.md)\n\n## License\n\n[MIT](LICENSE)\n",
"bytes": 34135,
"sha": "9d2d174787c5bf0c7aea9088f094e32c1eb6283e326548eb11238a625b29eeac",
"repo_slug": "keshrath/agent-knowledge",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/plg_keshrath_agent_knowledge_agent_knowledge_8e012836/readme"
}
![\"Knowledge](\"docs/assets/knowledge-light.png\")
![\"Session](\"docs/assets/search-light.png\")