agent-knowledge

面向 AI 编码助手的跨会话记忆与召回 —— 开箱即用地支持 Claude Code、Cursor、OpenCode、Cline、Continue.dev 和 Aider。Git 同步的知识库、混合语义 + TF-IDF 搜索、自动蒸馏并清洗机密信息。

基准测试： 在 longmemeval_s 上 R@5 = 97.2%（稀疏）/ 98.8%（混合），在更难的 longmemeval_m 分割上 86.0%（稀疏）/ 88.4%（混合） —— 这是公开的 LongMemEval 学术基准（Wu 等人，2024，ICLR 2025），每个分割 500 个完整问题，无需 LLM、无需 API 密钥，完全离线运行。在与论文的苹果对苹果复现中，R@5 比论文官方 flat-bm25 基线高出 +8.6 到 +13.2 个百分点。完整的按类别表格、复现说明和论文对比细节见 bench/README.md。

为什么

AI 编码会话是短暂的。当会话结束时，它学到的一切——架构决策、调试见解、项目上下文——都消失了。下一个会话从零开始。

agent-knowledge 通过两个互补系统解决这个问题：

1. 知识库 —— 一个 Git 同步的 Markdown 仓库，包含结构化条目（决策、工作流、项目上下文），跨会话和跨机器持久化。

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 的 Markdown 仓库，写入时自动提交并推送

• 自动过时检测 —— knowledge_analyze(action: "stale_by_code_activity") 将每个条目正文中提到的文件路径与最近会话摘要中的 filesModified 进行交叉引用。配合符号存在性精确层：检查条目引用的标识符（内联反引号 + 围栏代码块）是否在受影响的文件中；如果仍然存在，置信度下调 ×0.3。带有 evergreen: true 的条目豁免。

• 搜索缺口跟踪 —— knowledge_analyze(action: "search_gaps") 显示过去 since_days 内的零结果查询，按 token-Jaccard 相似度分组。这是“接下来应该写什么条目？”的最清晰信号。

• 分区优先级上下文打包器 —— knowledge(action: "wakeup") 在 token 预算内（默认 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）

• 常青条目 —— 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 push 前自动编辑

• 知识图 —— 条目之间的关系边（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 token 摘要（核心概念、活跃项目、最近决策、过时和缺口计数），用于会话开始时的定向

• 边来源 —— 图边跟踪 origin（manual、auto-link、distill、reflect），以便分析区分用户判断与自动化启发式

• 蒸馏中的确定性预提取 —— 会话摘要现在包括通过正则表达式从 bash/工具输出中提取的 git 提交、错误模式、访问的 URL 和更改的包（无 LLM 成本）

• 每次搜索命中的新鲜度元数据 —— 每个知识结果都携带 freshness: { body_age_days, last_accessed, access_count, verified_at, verification_age_days, evergreen }。代理读取信任信号并自行决定；我们不施加任何策略降级。

• 按类别衰减窗口 —— “未使用”过滤器和按类型图表遵循按类别阈值（项目 180 天、人员 365 天、决策 90 天、工作流 60 天、笔记 30 天），这样身份类内容不会仅仅因为不是每周重读而显得过时。

• 生命周期钩子 —— SessionStart 自动唤醒 + 摄取新鲜度检查，UserPromptSubmit 首次提示定向注入，PreCompact 内存刷新提示 + 蒸馏，SessionEnd 蒸馏。共六个钩子脚本，全部故障开放，每个可通过 AGENT_KNOWLEDGE_* 环境变量切换。参见 docs/HOOKS.md。

• 取代宿主自动记忆 —— 在具有每会话记忆系统的宿主上（Claude Code 的 ~/.claude/projects/*/memory/，其他 IDE 类似），将持久的用户事实和反馈路由到 agent-knowledge 而不是自动记忆。自动记忆是机器本地的，对其他机器不可见；agent-knowledge 是 git 同步的、跨机器的、可搜索的，并在唤醒时显示。参见 docs/USER-MANUAL.md 中的 Claude Code 集成说明。

代码库摄取

knowledge-ingest 技能从代码库目录填充或更新知识库。它使用 tree-sitter 进行零 token 的结构提取（类、函数、导入、调用图、原理注释），然后将文件聚类为子系统，并通过现有的 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 应用最大边际相关性（Maximal Marginal Relevance）重排序（消除 top-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"（默认）— 对候选条目进行评分 + 门控，写入日志，不修改知识库。

• promote_mode: "apply" — 提升通过的候选条目，写入日志，git 提交。

• 每次运行都会在 ~/agent-knowledge/.dreams/YYYY-MM-DD.md 中写入每个候选条目的信号分解和门控结果。以 . 开头的目录由 git 跟踪，但被排除在列表/搜索之外。

• 基于来源的再水合：如果候选条目的源会话文件在磁盘上不再存在，则跳过该候选条目（防止提升已删除的内容）。

• 带有 evergreen: true frontmatter 的条目永远不会被提升覆盖 — 活动会被追加。

写入基准测试工具：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 表中的类型化、加权边进行连接。支持十一种关系类型 — 8 种用于知识边，3 种用于代码结构：

知识：related_to, supersedes, depends_on, contradicts, specializes, part_of, alternative_to, builds_on 代码结构：calls, imports, inherits

• knowledge_graph(action: "link") 创建或更新边（可带 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") 删除具有特定来源的所有边（用于在重新摄取前清除过期的代码边）

代码图谱

代码结构边由 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 → 重复检查。返回 { path, autoLinks?, duplicateWarnings?, git }，状态码为 201。

这使得其他服务无需 MCP 连接即可通过 HTTP 进行写入。

agent-tasks KnowledgeBridge

agent-tasks 内置了 KnowledgeBridge，会在任务完成时自动将 learning 和 decision 工件推送到 agent-knowledge。条目会落入 decisions/ 目录并带有 frontmatter 标签（agent-tasks、项目名称、工件类型），自动进行嵌入索引，并自动链接到相似条目。无需配置——只要 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 提取、增量更新

• 架构 —— 源码结构、设计原则、数据库模式

• 仪表板 —— Web UI 视图与功能

• 更新日志

许可证

MIT