Lucent-Snow / agent-knowledge-mcp

# agent-knowledge-mcp
**让不同 Agent 共用一套简洁、可读的长期记忆。**
English · 接入自己的 VPS · 远程访问 · 多端同步 · 故障排查 · 文档格式
换一个聊天、模型或客户端，仍能找回之前确认的项目决定和经验。记忆保存在你自己的 Markdown 文件里，通过六个 MCP 工具读取和维护。
- **Markdown 是唯一真源**：可以直接阅读、编辑、备份和迁移。
- **本地即可使用**：中文词法检索，无 embedding、模型 API key 或外部检索服务。
- **按需加载**：基础上下文只包含使用说明、选定的 Context 和近期项目目录；正文按需读取。
- **跨端共享**：本地 MCP、远程 HTTP MCP，以及可选的 Syncthing 文件同步。
## 开始使用
需要 **Node.js 22 或更新版本**，以及支持本地 stdio MCP 的 Agent 客户端。
在客户端的 MCP 配置中加入：
 [code] 
启动客户端后，包会在首次运行时创建 `~/.agent-knowledge/` 和一份双语记忆使用说明。用户资料和项目内容从空白开始；重启和升级不会覆盖已有记忆。
不同客户端的配置位置和结构可能不同。上述是常见 JSON 形式；如果客户端找不到 `npx`，填写它在本机的绝对路径。Windows 客户端若要求可执行文件名，可使用 `npx.cmd`。
也可以全局安装，再使用 `agent-knowledge-mcp` 命令：
 [code] 
### 给 Agent 的指令
把下面这段复制到客户端的模型提示词或 Agent 指令文件。MCP 提供工具和引导，但不会替你修改客户端提示词，也不能保证客户端自动读取基础上下文。
 [code] 
### 验证一次记忆往返
先对 Agent 说：
> 读取这套记忆系统的说明，并检查记忆库是否正常。
然后：
> 记住“纸飞机”项目的决定：第一版只支持本地使用，远程部署后续再做。
开启新会话后：
> “纸飞机”项目第一版之前决定支持什么？
后来改变决定，可以说：
> 更新“纸飞机”项目的记忆：第一版现在也支持远程部署，并保留改变决定的理由。
Agent 会查找已有主题、读取最新版本，再更新它。系统不会每回合自动保存聊天；记忆质量依赖这份使用契约和 Agent 在任务中的判断。
## 记忆如何组织
 [code] 
| 类型 | 保存什么 | 默认基础上下文 |
|---|---|---|
| Context | 跨任务反复需要的稳定约定 | global 和匹配 scope 的文档；`ambient: false` 可退出 |
| Project | 目标、状态、决定和理由 | 最近 30 天更新的最多 12 个项目摘要 |
| Note | 方法、经验、证据、专题结论 | 按需查找和读取 |
| Identity | 人物、自我或关系背景 | 不默认加载；可显式查找和读取 |
Identity 的加载规则不构成权限隔离。所有连接此库的客户端，都可以使用全部六个工具。
| 工具 | 用途 |
|---|---|
| `knowledge_context` | 有长度上限的基础上下文，默认不含 Identity、Note 或项目正文 |
| `knowledge_find` | 浏览摘要，或按标题、描述、tags、正文等词法检索 |
| `knowledge_read` | 正文、元数据、etag；关系作为独立字段返回 |
| `knowledge_write` | 创建或更新；支持精确 patch、append、replace |
| `knowledge_delete` | 使用最新 etag 永久删除；普通退役优先归档 |
| `knowledge_status` | 检查坏文档和同步冲突，不自动合并 |
## 配置和命令
 [code] 
`AGENT_KNOWLEDGE_ROOT` 和 `AGENT_KNOWLEDGE_SCOPE` 也可通过 MCP 配置的 `env` 设置。命令行参数优先。
默认 context 最多 16,000 字符，超出时返回截断提示和来源 URI。大参考文档建议设 `ambient: false`，再显式检索。
初始化不会询问或生成个人画像。已有库启动时不会自动插入说明；需要时显式执行 `init`。删除内置说明后普通重启不会恢复它。包安装阶段不运行初始化脚本。
## 多端与远程
两种方式可以单独使用，也可以组合：
- **远程访问**：在常在线设备上运行 HTTP MCP，其他客户端连接同一库。支持 Bearer token，另有需要明确开启的 URL 凭证模式。部署说明
- **多端同步**：每台设备使用本地 MCP，通过 Syncthing 同步 Markdown 副本；离线仍可读写。包提供 `sync-prepare`，Syncthing 需另外安装和配对。接入说明
本机工具写入使用跨进程锁，并在锁内检查 etag。外部编辑器、Syncthing 和其他设备不参与此锁；同步是最终一致，不是全局事务。冲突副本需要显式处理。同步不替代备份。
HTTP 凭证持有人可以读取、写入和删除整个库。不同信任范围请使用不同 root 和独立服务。
## 让 Agent 帮你接入自己的 VPS
可以把这个仓库的 README 链接交给有终端和 SSH 能力的 Agent，并复制下面的请求。Agent 的可用工具和用户授权决定它能执行哪些操作；账号登录等需要本人完成的步骤由它明确指出。
 [code] 
没有 VPS 也可以先用本地核心。已有库不需要重新填写个人资料。上述是部署请求；日常记忆使用指令仍采用前文“给 Agent 的指令”。
文档适用范围与已验证的发布路径不同：发布验证包括官方 SDK、隔离 Syncthing 节点和跨平台测试；具体云厂商、反向代理与网页客户端需要在用户自己的环境里验收。按现象排查
## 开发
 [code] 
测试只使用临时目录，包括真实 stdio/HTTP MCP 往返、跨进程并发修改、上下文边界、坏文档和冲突检查。CI 在 Linux、macOS、Windows 上运行 Node 22/24。
格式与实现边界见 docs/format.md；开发约定见 AGENTS.md。
MIT License.
## 友情链接
* Linux DO