Allows AI agents to read, search, add, update, and delete shared long-term memory notes stored as Markdown files in an Obsidian Vault, with version history, recovery, and optional indexing support.
让不同 AI Agent，接续同一份由你掌控的长期记忆。
把偏好、项目决策和经验保存在自己的 Obsidian Vault 中，通过 MCP 让多个 Agent 检索和更新。记忆是普通 Markdown 文件，可以直接阅读、编辑、备份，也可以导出带到另一台电脑。
本地 Markdown · Obsidian · 通用 MCP 接入 · 版本恢复 · uv 管理依赖
快速开始 · 接入 MCP · 跨电脑迁移 · WSL2 · 常见问题 · 开发
能力 | 使用方式 |
多 Agent 共用记忆 | 在兼容的 MCP 软件中添加同一个本机服务，无需重复导入笔记 |
与 Obsidian 共用文件 | 直接阅读、编辑 Vault 内的 |
自动沉淀有用背景 | 让 Agent 按记忆规则检索主题、保存稳定偏好和明确结论 |
查看与恢复改动 | 本机版本历史、回收站、导入前恢复点，以及更新时的版本检查 |
换电脑继续使用 | 导出 ZIP，在另一台电脑预览并导入，处理重复内容和冲突 |
日常使用不需要手动执行 Git 命令，也不需要额外的模型 API 密钥。本项目不提供跨设备实时同步；自动记录依赖 Agent 执行规则，不等于完整聊天自动存档。
当前为早期版本。 Windows x64 已实测；macOS/Linux 提供启动脚本和 CI 配置，尚未完成实机验证。WSL2 的接入条件见下文，详细测试范围见验证记录。
Related MCP server: Tacitus MCP Server
安装 uv 0.13.1 或更新版本，并确保它已加入 PATH。安装方法见 uv 官方文档。
在 GitHub 仓库页面选择 Code → Download ZIP，解压到自己的项目目录。
不必单独安装 Python：启动器会通过 uv 使用 Python 3.12，并在需要时下载。
首次启动需要联网下载依赖。依赖齐备后，本地记忆服务可离线运行；所用 AI 客户端是否需要联网，由该客户端决定。
系统 | 启动方式 |
Windows | 双击 |
macOS | 打开 |
Linux | 在项目目录运行 |
启动后打开 http://127.0.0.1:8765。启动器会按 uv.lock 自动准备独立环境，保持启动进程运行即可继续提供记忆服务。
进入 工作空间设置 → Obsidian Vault，填写 Vault 根目录的绝对路径并保存。
你的 Obsidian Vault/
└── AI-Memory/
├── preference/ # 个人偏好
├── decision/ # 项目决策
├── experience/ # 经验与方法
└── note/ # 其他记忆本项目只管理 AI-Memory/ 子目录。默认位置为项目内的 MemoryVault/AI-Memory/；也可以在 Obsidian 中把 MemoryVault 打开为仓库。记忆目录里的双向链接仍由 Obsidian 使用。
同一页可点击 安装 Basic Memory，准备本地索引引擎。它是可选组件：未安装或暂时不可用时，基础读写、中文文本匹配和导入导出仍可使用。
切换 Vault 会保留旧目录中的笔记，不会自动搬迁。保存失败时继续使用原记忆库，并显示具体原因。
进入 Agent 接入 → 在其他软件中接入 → 查看连接参数，在目标软件自己的 MCP 设置中添加服务。也可以使用下方的可选自动配置入口。
当前入口适用于支持 Streamable HTTP 和自定义认证请求头的本机 MCP 客户端。
字段 | 填写内容 |
服务名称 |
|
连接类型 | Streamable HTTP；部分软件标为 HTTP |
服务地址 | 默认 |
认证请求头 |
|
认证值 | 从工作台复制，已包含 |
工作台支持复制地址、显示或隐藏认证值、复制 JSON、下载 JSON，以及复制自动记忆规则。
{
"mcpServers": {
"obsidian_shared_memory": {
"type": "http",
"url": "http://127.0.0.1:8765/mcp",
"headers": {
"Authorization": "Bearer <从工作台复制的本机令牌>"
}
}
}
}这是常见格式模板，具体字段以目标软件为准。无法直接导入时，可按上表手动填写。如果软件会自动添加 Bearer 前缀，只填写令牌部分。
示例中的令牌是占位符。工作台导出的真实配置含访问令牌，请仅导入你信任的软件。
仅支持 stdio、旧式 HTTP+SSE，或只能使用 OAuth 的软件，不能直接使用当前入口。云端客户端也无法通过它自己的 127.0.0.1 访问你的电脑。完整兼容范围见通用 MCP 接入说明。
两个快捷入口会备份并增量合并客户端配置，添加 MCP 服务、全局记忆规则和 SessionStart 摘要 hook，保留其他已有设置。连接前可以预览将修改的文件；客户端要求的重启、MCP 或 hook 信任步骤仍需完成。
Windows 下也可双击 Connect-Codex.cmd 或 Connect-Claude.cmd。移除时，在工作台选择 移除本项目配置。
手动添加 MCP 与自动配置使用同一份记忆。若希望手动接入的 Agent 自动检索和记录，可将工作台中的 自动记忆规则 粘贴到该软件的全局指令中。
在第一个 Agent 中使用以下示例：
请使用 obsidian_shared_memory 记住：示例项目的接口文档使用中文。保存为项目决策，项目名填写“接入测试”。
再在第二个 Agent 的新会话中说：
请使用 obsidian_shared_memory 的 recall 工具，查询“接入测试”项目的接口文档语言，并给出记忆标题和来源。
在工作台中确认笔记已经出现。仅显示“服务已添加”不能证明实际读写成功。
也可导入 examples/示例记忆包.zip 体验界面，其中的三条笔记均明确标记为示例。
电脑 A 导出 → 传递 ZIP → 电脑 B 预览并导入。
在电脑 A 的 导入与导出 页面导出记忆包。
用 U 盘或自己选择的文件传输方式，把 ZIP 带到电脑 B。
在电脑 B 安装并启动本项目，选择记忆包，预览后确认导入。
导入情况 | 处理方式 |
相同 ID、相同内容 | 跳过，重复导入不会重复创建 |
相同 ID 内容不同，或文件名冲突 | 默认保留两份；也可选择保留本地或覆盖 |
本地笔记未出现在记忆包中 | 保留本地笔记 |
导入过程中失败或中断 | 使用导入前恢复点回滚 |
记忆包包含 Markdown、稳定 ID 和校验清单。本机历史、回收站、访问令牌、客户端配置和索引不随包迁移。 v1 仅迁移文字笔记，不打包附件，也不改写笔记中的绝对路径与外部链接。
MCP JSON 配置用于添加服务，记忆 ZIP 用于迁移笔记；接入另一个软件不需要重新导入记忆。
推荐保留 Windows 上的记忆服务，让 WSL2 中的 Agent 通过 MCP 访问同一份文件。
WSL2 网络模式 | 访问当前 Windows 服务 |
镜像模式 | 可按该网络模式的能力，通过 |
默认 NAT 模式 | 当前不能直接连接，需要额外桥接或适配 |
Windows 11 22H2 及以上支持镜像模式，配置方式见微软官方 WSL 网络文档。本项目仅监听 Windows 回环地址，并校验主机名；在 NAT 模式下，仅替换 URL 为 Windows IP 不足以接通。
连接参数需要添加到 WSL 内实际运行的 Agent 的设置中。当前尚未完成 WSL 内部的实际 MCP 联通测试，表中说明的是网络与实现条件。
操作 | 行为 |
Agent 新增 | 通过 MCP 网关原子写入 Markdown，并记录本机历史 |
Agent 修改 | 必须提供读取时的版本；过时写入会被拒绝 |
Obsidian 编辑 | 下次扫描时观察文件变化，并记录可见版本 |
工作台或 Agent 删除 | 移到本机回收站，可在设置中恢复 |
导入记忆包 | 先预览，再创建恢复点并应用变化 |
程序关闭期间的中间编辑无法全部记录；Obsidian 自己删除的文件由其回收站管理。自动记忆规则可能受到客户端审批或项目级指令影响，是否保存以实际工具返回和落盘笔记为准。
flowchart LR
Agents["MCP 客户端 / AI Agent"] -->|检索与写入| Gateway["苔记 MCP 网关"]
UI["本地工作台"] --> Gateway
Gateway -->|原子写入| Notes["AI-Memory / Markdown"]
Obsidian["Obsidian"] <-->|阅读与编辑| Notes
Notes -->|索引| Engine["Basic Memory · 可选"]
Gateway -.->|查询| Engine
Gateway --> History["本机历史与恢复点"]路径 | 内容 |
| 权威 Markdown 笔记 |
| 本机版本历史与活动 |
| 库恢复点与可恢复删除 |
| 访问令牌与原客户端配置备份 |
| 索引引擎配置与本地数据 |
| 主程序与引擎各自的 uv 环境 |
| 依赖缓存与按需准备的 Python |
服务仅监听 127.0.0.1，MCP 使用本机令牌，工作台 API 校验同源与请求令牌。索引引擎默认关闭语义模型、云模式和自动更新，不额外调用模型 API。
配置备份可能包含原客户端的敏感设置。发布源码时，请保留 .gitignore，并将 .local/、.runtime/、真实记忆库和含令牌的 MCP JSON 留在本机；通过网页上传文件时同样需要排除它们。源码打包脚本会排除运行数据，只附带明确标记的示例记忆。
本项目的文件范围约束不能限制 Agent 自身已有的 shell 或文件访问权限。记忆内容应作为资料使用，不应把笔记中的不可信文本当作执行指令。
确认当前用户可以访问目标目录。由 Agent 沙箱启动的进程可能无法写入工作区外的 Vault 或客户端配置目录，可授权对应目录，或自行打开项目启动脚本后重试。
Windows 的客户端接入也可以使用 Connect-Codex.cmd / Connect-Claude.cmd。错误弹窗会保留具体原因；自动配置修改前有备份，保存目录失败时保留原记忆库。
MCP 提供记忆工具，Agent 决定何时调用。将自动记忆规则加入客户端的全局指令，再检查工具调用和工作台中的实际笔记。项目只鼓励沉淀稳定事实、明确决策与可复用经验，不读取或存档完整聊天记录。
旧笔记仍在原目录。切换只改变活动记忆库，不自动搬迁；如需迁移，可在旧库导出记忆包，再切换到新库并导入。
基础记忆读写和中文文本匹配不依赖索引引擎。可先使用工作台搜索或 MCP 的 recall 工具，再在设置中安装、重启引擎或查看日志。默认未启用语义模型，不能把文本匹配当作完整的语义检索。
Python 3.12，依赖由 uv 管理。主程序使用根目录的 pyproject.toml / uv.lock，可选引擎使用 engine/ 下的独立项目和锁文件。
uv sync --locked
uv run --locked pytest -q
uv run --locked --no-dev -m shared_memory --no-browser主程序使用 FastAPI 与官方 Python MCP SDK，界面为本地静态资源，无需前端构建或外部 CDN。索引侧进程固定为 Basic Memory 0.23.2；界面安装器通过 uv sync --locked 准备独立环境，不将其依赖混入主程序环境。
MCP 工具 | 用途 |
| 检索相关记忆，可按项目筛选 |
| 读取全文及当前版本 |
| 新增记忆 |
| 使用版本检查更新记忆 |
| 查看最近更新 |
| 按用户要求将记忆移入回收站 |
测试覆盖并发版本检查、历史恢复、迁移往返、重复导入、冲突处理、失败回滚、路径校验、访问边界和配置合并。跨平台执行定义见 GitHub Actions 配置，实际执行结果见验证记录。
源码打包入口为 tools/build_package.py。真实索引引擎测试位于 tests/engine_smoke.py，需要已安装的固定依赖环境与独立测试数据目录，不应指向真实 Vault。
本项目集成层采用 MIT License。Basic Memory、MCP Python SDK 和 uv 等第三方组件保留各自许可证，见 THIRD_PARTY.md。
Obsidian、Codex、Claude Code 是各自厂商的独立产品，本项目与其无隶属关系。
This server cannot be deployed
Markdown notes and whiteboards your AI agent can read and write.
Persistent docs and memory for AI agents — read, write, organize & search a shared workspace.
Shared long-term memory for AI agents: save and recall context as a searchable knowledge graph.
Long-term memory and a knowledge graph for AI agents: recall, notes, secrets and data sources.
