agent-knowledge

agent-knowledge

为 AI 编码助手提供跨会话记忆与回忆能力 —— 开箱即用，支持 Claude Code、Cursor、OpenCode、Cline、Continue.dev 和 Aider。提供 Git 同步的知识库、混合语义 + TF-IDF 搜索，以及自动提炼并清除机密信息。

基准测试： 在 longmemeval_s 上，R@5 = 97.2%（稀疏）/ 98.8%（混合）；在难度更高的 longmemeval_m 划分上，R@5 = 86.0%（稀疏）/ 88.4%（混合）——采用公开的 LongMemEval 学术基准（Wu 等，2024，ICLR 2025），每个划分均使用完整的 500 个问题，不需要大模型或 API 密钥，完全离线运行。在同等条件的复现中，R@5 比论文官方的 flat-bm25 基线高 8.6 个百分点至 13.2 个百分点。完整分类表、复现说明和论文对比详情见 bench/README.md。

在 Claude Code 中，agent-knowledge 插件会添加 /knowledge 面板：让知识库显示在对话旁边。了解其工作原理（附图片）：用户手册。

为什么

AI 编码会话是短暂的。会话结束时，它学到的一切——架构决策、调试心得、项目背景——都会消失。下一次会话只能从头开始。

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

1. 知识库——由 Git 同步的 Markdown 资料库，包含结构化条目（决策、工作流、项目背景），可在不同会话和机器间持续保存。
2. 会话搜索——对所有编码工具的会话记录进行 TF-IDF 排序的全文搜索，让 Agent 能回忆之前发生的事情，无论当时使用的是哪种工具。

支持的工具

自动发现所有主流 AI 编码助手的会话——只要安装了工具，其会话就会自动显示。

工具	格式	自动检测路径
Claude Code	JSONL	~/.claude/projects/
Cursor	JSONL	~/.cursor/projects/*/agent-transcripts/
Codex CLI	JSONL	~/.codex/projects/
Aider	Markdown/JSONL	项目目录中的 .aider.chat.history.md / .aider.llm.history
Continue.dev	JSON	~/.continue/projects/
Cline	JSON	VS Code 的 globalStorage saoudrizwan.claude-dev/tasks/
OpenCode	SQLite	~/.local/share/opencode/opencode.db（或 $OPENCODE_DATA_DIR）

无需配置。可通过 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") 会在令牌预算内（默认为 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，即可使条目免于排名衰减，并在晋升时仅允许追加内容。/knowledge 窗格会标记这些条目。
• 作者署名 -- 可选的 author: <string> frontmatter，会随条目保留，并由 REST API 返回。
• 代码图谱解析 -- 用于代码结构的 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 同步，会话则从各工具的本地存储读取
• Claude Code 中的 /knowledge 窗格 -- 在对话旁浏览和搜索知识库（agent-knowledge 插件）
• 机密信息清理 -- 推送到 Git 前自动隐藏 API 密钥、令牌、密码和私钥
• 知识图谱 -- 条目之间的关系边（related_to、supersedes、depends_on、contradicts、specializes、part_of、alternative_to、builds_on），支持 BFS 遍历
• 置信度/衰减评分 -- 根据访问频率和时间新近度为条目评分；自动将条目从候选提升为已确立，再提升为已验证
• 记忆整合 -- 写入时通过 TF-IDF 检测重复内容（对相似条目发出警告），还可通过 knowledge_analyze(action: "consolidate") 批量扫描重复项
• 反思循环 -- knowledge_analyze(action: "reflect") 会找出未连接的条目，并生成结构化提示词，让 Agent 识别新的图谱连接
• 写入时自动关联 -- 新条目会在余弦相似度 > 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 和变更的软件包，并纳入会话摘要（不产生大模型费用）
• 每个搜索结果均带有新鲜度元数据 — 每条知识结果都包含 freshness: { body_age_days, last_accessed, access_count, verified_at, verification_age_days, evergreen }。Agent 会读取信任信号并自行判断；我们不会强制降低排名。
• 按类别配置衰减窗口 — “未使用”筛选器和 bytype 图表会遵循各类别的阈值（项目 180d、人员 365d、决策 90d、工作流 60d、笔记 30d），避免仅因身份类内容没有每周重读就将其视为过时。
• 生命周期钩子 — SessionStart 自动唤醒并检查导入新鲜度，UserPromptSubmit 在首次提示词时定向注入，PreCompact 提醒刷新记忆并进行蒸馏，SessionEnd 进行蒸馏。共 6 个钩子脚本，全部采用失败时放行机制，每个都可通过 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 Agent）

添加到 MCP 客户端配置中（Claude Code、Cline 等）：

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

第一个 MCP 进程还会在 127.0.0.1:3423 上提供本地 REST API（hooks、/knowledge 面板和 agent-tasks 会调用此 API）；该进程退出后，另一个正在运行的会话会接管该端口。

有关客户端特定的说明（Claude Code、Cursor、Windsurf、OpenCode），请参阅设置指南。

选项 2：Claude Code 插件

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

此插件包含 MCP 服务、knowledge-ingest 技能和 /knowledge 面板（Claude Code 2.1.289+）。

MCP 工具（6 个）

知识库

工具	操作	描述	参数
knowledge	list	按类别和／或标签列出条目	category?、tag?
	read	读取指定条目	path（必填）
	write	创建／更新条目（自动进行 git 同步）	category、filename、content（均必填）
	delete	删除条目（自动进行 git 同步）	path（必填）
	sync	手动执行 git 拉取和推送	--
	wakeup	返回 L0 身份信息和 L1 权重最高的条目（按 Token 预算限制）	token_budget?、category?

搜索

工具	描述	参数
knowledge_search	通用混合 TF-IDF + 语义搜索（不设置 scope）	query、project?、role?、max_results?、ranked?、semantic?、category?、category_mode?、mmr?、mmr_lambda?、explain?
	限定范围的仅会话回忆（设置 scope 时）	query、scope、project?、max_results?

响应结构：{mode: "general" | "scoped", sessions, knowledge}。按设计，限定范围模式会返回 knowledge: []。

范围：errors、plans、configs、tools、files、decisions、all。

搜索选项：

• mmr: true 会应用最大边际相关性重新排序（消除 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}。

会话

工具	操作	描述	参数
knowledge_session	list	列出会话及其元数据	project?
	get	获取完整的会话对话	session_id、project?、include_tools?、tail?
	summary	会话摘要（主题、工具、文件）	session_id、project?

知识图谱

工具	操作	描述	参数
knowledge_graph	link	在条目之间创建或更新边	source、target、rel_type、strength?
	unlink	移除条目之间的边	source、target、rel_type?
	invalidate	将边标记为过期（设置 valid_to）	source、target、rel_type?、valid_to?
	list	列出边	entry?、rel_type?、as_of?
	traverse	从某个条目开始进行有向 BFS 遍历	entry、depth?、direction?、rel_type?、as_of?
	bulk_link	批量创建边（代码图谱导入）	edges（包含 {source, target, rel_type, strength?, origin?} 的数组）
	unlink_by_origin	按来源删除所有边	origin

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

遍历方向：outbound（源→目标）、inbound（目标→源）、both（默认，无向）

分析

工具	操作	描述	参数
knowledge_analyze	consolidate	查找近似重复的条目	category?、threshold?
	reflect	查找未关联的条目以便建立链接	category?、max_entries?
	god_nodes	连接最多的条目（度中心性）	top_n?
	bridges	跨类别连接项（介数中心性）	top_n?
	gaps	按成熟度筛选孤立条目（0-1 条边）	max_entries?
	brief	缓存的约 200 token 知识库摘要	--

管理

工具	操作	描述	参数
knowledge_admin	status	向量存储统计信息	--
	config	查看或更新配置	git_url?、memory_dir?、auto_distill?
	rebuild_embeddings	为所有知识条目重新生成嵌入（在切换提供商时很有用）	--
	prune_orphans	删除磁盘上已不存在的会话对应的嵌入	vacuum?、force_vacuum?
	vacuum	回收向量存储中的空闲页	--
	promote	评分并设有门槛的晋升工具	promote_mode?（apply|explain）、min_score?、min_recall_count?、min_unique_queries?

评分晋升工具

每个项目级候选项都会根据六项信号评分（相关性 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

仅监听回环地址（127.0.0.1），仅支持 JSON。每个请求都会经过安全检查：来自外部的 Host 或任何 Origin 标头都会导致 403，且请求正文必须为 application/json。带斜杠的 :path 会以编码形式发送（notes%2Fx.md）。

方法	端点	调用方	描述
GET	/health	面板、钩子	状态、版本、条目数
GET	/api/overview	/knowledge 面板	数量、类别、近期事件
GET	/api/knowledge?category=&tag=	面板	列出条目及其评分
GET	/api/knowledge/search?q=&max_results=	面板、opencode 插件	搜索知识库
GET	/api/knowledge/:path	面板	读取单个条目
GET	/api/knowledge/:path/links	面板	条目的图谱边，每条边均包含另一端的标题
DELETE	/api/knowledge/:path	面板	删除条目（与 git 同步）
POST	/api/knowledge	agent-tasks KnowledgeBridge	写入条目（完整写入流程）
POST	/api/knowledge/sync	面板	git 拉取 + 推送
GET	/api/analysis	面板	枢纽和孤立条目
GET	/api/sessions?limit=&offset=&project=	面板	分页获取会话：{ sessions, total }
GET	/api/sessions/search?q=&role=	面板	搜索会话
GET	/api/sessions/:id/summary	面板	会话摘要
POST	/api/events	sessionend-distill 钩子	面板显示的回执

架构

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

知识图谱

条目和代码符号可以通过类型化、有权重的边相连，这些边存储在专用的 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") 创建或更新一条边（可选强度为 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

条目会根据访问次数自动进入成熟阶段：

阶段	访问次数	倍数
candidate	< 5	0.5x
established	5-19	1.0x
proven	20+	1.5x

频繁访问的条目在搜索排名中上升；过时条目则会随时间衰减。

搜索功能

TF-IDF 排名 -- 根据词频-逆文档频率为结果评分。罕见词会提高相关性。全局索引会缓存 60 秒。

模糊匹配 -- 使用滑动窗口计算 Levenshtein 编辑距离。阈值可配置（默认值为 0.7）。

通过 knowledge_search 的 scope 参数进行范围限定的检索：

范围	匹配内容
errors	堆栈跟踪、异常、失败的命令
plans	架构、TODO、实现步骤
configs	设置、环境变量、配置文件
tools	MCP 工具调用、CLI 命令
files	文件路径、修改
decisions	权衡、理由、选择

集成

REST 写入端点

POST /api/knowledge 接受 { category, filename, content }，并运行完整的写入流程：git pull → 文件写入 → 嵌入索引 → 自动关联 → git push → 重复项检查。成功时返回状态码 201 和 { path, autoLinks?, duplicateWarnings?, git }。

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

agent-tasks KnowledgeBridge

agent-tasks 内置了 KnowledgeBridge，可在任务完成时自动将 learning 和 decision 工件推送到 agent-knowledge。条目会写入 decisions/，并附带 frontmatter 标签（agent-tasks、项目名称、工件类型），自动建立嵌入索引，并自动关联相似条目。无需配置：只要有任意会话正在运行 agent-knowledge，其位于 127.0.0.1:3423 的 REST API 就会响应请求。

测试

npm test              # 604 tests across 39 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），无需配置。

核心

变量	默认值	描述
AGENT_KNOWLEDGE_MEMORY_DIR	~/agent-knowledge	与 Git 同步的知识库目录
AGENT_KNOWLEDGE_GIT_URL	--	Git 远程 URL（如果目录不存在，则自动克隆）
AGENT_KNOWLEDGE_AUTO_DISTILL	true	自动将会话见解提炼到知识库中
AGENT_KNOWLEDGE_INDEX_VERBATIM	true	将原始会话消息块索引到向量存储中，以便稍后检索对话。设为 false 可在大规模使用时节省磁盘空间。
AGENT_KNOWLEDGE_DATA_DIR	（平台配置）	覆盖主要宿主数据根目录。通常情况下请留空——适配器会自动检测 ~/ 下所有已知的宿主根目录。
AGENT_KNOWLEDGE_EXTRA_SESSION_ROOTS	--	额外的会话目录，以逗号分隔。会与自动检测到的目录合并。
AGENT_KNOWLEDGE_PORT	3423	本地 REST API 端口（/knowledge 面板、钩子、agent-tasks）
AGENT_KNOWLEDGE_HOST	127.0.0.1	REST 绑定地址

嵌入

变量	默认值	描述
AGENT_KNOWLEDGE_EMBEDDING_PROVIDER	local	local | openai | claude | gemini
AGENT_KNOWLEDGE_EMBEDDING_ALPHA	0.3	TF-IDF 与语义混合权重（0 = 纯语义，1 = 纯 TF-IDF）
AGENT_KNOWLEDGE_EMBEDDING_MODEL	--	覆盖提供方的默认模型
AGENT_KNOWLEDGE_EMBEDDING_IDLE_TIMEOUT	60	卸载本地模型前的秒数（0 = 保持加载状态）
AGENT_KNOWLEDGE_EMBEDDING_THREADS	（自动）	本地提供方的 ONNX / OMP 线程数

API 密钥

项目范围的覆盖项优先于标准密钥。任选其一即可；使用项目范围的形式，可以让 agent-knowledge 使用与环境中其他部分不同的密钥。

变量	回退值	描述
AGENT_KNOWLEDGE_OPENAI_API_KEY	OPENAI_API_KEY	OpenAI 嵌入
AGENT_KNOWLEDGE_ANTHROPIC_API_KEY	ANTHROPIC_API_KEY	Claude / Voyage 嵌入
AGENT_KNOWLEDGE_GEMINI_API_KEY	GEMINI_API_KEY	Gemini 嵌入

钩子

变量	默认值	描述
AGENT_KNOWLEDGE_AUTOWAKE	1	自动将 knowledge(action: wakeup) 内容注入 SessionStart。设置为 0 可禁用。
AGENT_KNOWLEDGE_WAKEUP_BUDGET	800	唤醒内容的令牌数
AGENT_KNOWLEDGE_FIRSTPROMPT_INJECT	1	针对第一个用户提示词运行 knowledge_search，并注入排名靠前的结果。设置为 0 / false / off 可禁用。
AGENT_KNOWLEDGE_FIRSTPROMPT_BUDGET	600	首个提示词注入的令牌数（限制范围为 [100, 8000]）
AGENT_KNOWLEDGE_FIRSTPROMPT_MAX_HITS	4	附加到首个提示词的知识条目数上限（限制范围为 [1, 20]）
AGENT_KNOWLEDGE_PRECOMPACT_NUDGE	1	压缩前，提示 Agent 通过 knowledge(action: write) 保存上下文。设置为 0 可禁用提示；设置为 off 可同时禁用提示和磁盘转储。

外部工具覆盖项

变量	默认值	描述
OPENCODE_DATA_DIR	~/.local/share/opencode	覆盖 OpenCode 会话数据库的存放位置（OpenCode 自身的环境变量，由我们的适配器遵循）

文档

• 设置指南 — 安装、客户端设置（Claude Code、OpenCode、Cursor、Windsurf）、钩子、技能
• 摄取指南 — 代码库摄取技能、tree-sitter 提取、增量更新
• 架构 — 源码结构、设计原则、数据库架构
• 钩子 — Claude Code 生命周期钩子
• 更新日志

许可证

MIT