# 苔记 · Obsidian Shared Memory

**让不同 AI Agent，接续同一份由你掌控的长期记忆。**

把偏好、项目决策和经验保存在自己的 Obsidian Vault 中，通过 MCP 让多个 Agent 检索和更新。记忆是普通 Markdown 文件，可以直接阅读、编辑、备份，也可以导出带到另一台电脑。

本地 Markdown · Obsidian · 通用 MCP 接入 · 版本恢复 · uv 管理依赖

[快速开始](#快速开始) · [接入 MCP](#接入-mcp) · [跨电脑迁移](#跨电脑迁移) · [WSL2](#wsl2) · [常见问题](#常见问题) · [开发](#开发)

## 可以做什么

| 能力 | 使用方式 |
| --- | --- |
| 多 Agent 共用记忆 | 在兼容的 MCP 软件中添加同一个本机服务，无需重复导入笔记 |
| 与 Obsidian 共用文件 | 直接阅读、编辑 Vault 内的 `AI-Memory/` Markdown 笔记 |
| 自动沉淀有用背景 | 让 Agent 按记忆规则检索主题、保存稳定偏好和明确结论 |
| 查看与恢复改动 | 本机版本历史、回收站、导入前恢复点，以及更新时的版本检查 |
| 换电脑继续使用 | 导出 ZIP，在另一台电脑预览并导入，处理重复内容和冲突 |

日常使用不需要手动执行 Git 命令，也不需要额外的模型 API 密钥。本项目不提供跨设备实时同步；自动记录依赖 Agent 执行规则，不等于完整聊天自动存档。

**当前为早期版本。** Windows x64 已实测；macOS/Linux 提供启动脚本和 CI 配置，尚未完成实机验证。WSL2 的接入条件见[下文](#wsl2)，详细测试范围见[验证记录](docs/VALIDATION.md)。

## 快速开始

### 1. 准备 uv 和项目源码

- 安装 **uv 0.13.1 或更新版本**，并确保它已加入 PATH。安装方法见 [uv 官方文档](https://docs.astral.sh/uv/getting-started/installation/)。
- 在 GitHub 仓库页面选择 **Code → Download ZIP**，解压到自己的项目目录。
- 不必单独安装 Python：启动器会通过 uv 使用 Python 3.12，并在需要时下载。

首次启动需要联网下载依赖。依赖齐备后，本地记忆服务可离线运行；所用 AI 客户端是否需要联网，由该客户端决定。

### 2. 启动本地工作台

| 系统 | 启动方式 |
| --- | --- |
| Windows | 双击 [`Start.cmd`](Start.cmd) |
| macOS | 打开 [`Start.command`](Start.command)；也可在项目目录运行 `sh ./start.sh` |
| Linux | 在项目目录运行 `sh ./start.sh` |

启动后打开 **<http://127.0.0.1:8765>**。启动器会按 `uv.lock` 自动准备独立环境，保持启动进程运行即可继续提供记忆服务。

### 3. 选择 Obsidian Vault

进入 **工作空间设置 → Obsidian Vault**，填写 Vault 根目录的绝对路径并保存。

```text
你的 Obsidian Vault/
└── AI-Memory/
    ├── preference/   # 个人偏好
    ├── decision/     # 项目决策
    ├── experience/   # 经验与方法
    └── note/         # 其他记忆
```

本项目只管理 `AI-Memory/` 子目录。默认位置为项目内的 `MemoryVault/AI-Memory/`；也可以在 Obsidian 中把 `MemoryVault` 打开为仓库。记忆目录里的双向链接仍由 Obsidian 使用。

同一页可点击 **安装 Basic Memory**，准备本地索引引擎。它是可选组件：未安装或暂时不可用时，基础读写、中文文本匹配和导入导出仍可使用。

> 切换 Vault 会保留旧目录中的笔记，不会自动搬迁。保存失败时继续使用原记忆库，并显示具体原因。

### 4. 连接你的 Agent

进入 **Agent 接入 → 在其他软件中接入 → 查看连接参数**，在目标软件自己的 MCP 设置中添加服务。也可以使用下方的可选自动配置入口。

## 接入 MCP

### 在软件自己的设置中添加

当前入口适用于支持 **Streamable HTTP** 和自定义认证请求头的本机 MCP 客户端。

| 字段 | 填写内容 |
| --- | --- |
| 服务名称 | `obsidian_shared_memory` |
| 连接类型 | Streamable HTTP；部分软件标为 HTTP |
| 服务地址 | 默认 `http://127.0.0.1:8765/mcp`，以工作台显示值为准 |
| 认证请求头 | `Authorization` |
| 认证值 | 从工作台复制，已包含 `Bearer ` 前缀 |

工作台支持复制地址、显示或隐藏认证值、复制 JSON、下载 JSON，以及复制自动记忆规则。

<details>
<summary>JSON 配置模板</summary>

```json
{
  "mcpServers": {
    "obsidian_shared_memory": {
      "type": "http",
      "url": "http://127.0.0.1:8765/mcp",
      "headers": {
        "Authorization": "Bearer <从工作台复制的本机令牌>"
      }
    }
  }
}
```

这是常见格式模板，具体字段以目标软件为准。无法直接导入时，可按上表手动填写。如果软件会自动添加 Bearer 前缀，只填写令牌部分。

示例中的令牌是占位符。工作台导出的真实配置含访问令牌，请仅导入你信任的软件。

</details>

仅支持 stdio、旧式 HTTP+SSE，或只能使用 OAuth 的软件，不能直接使用当前入口。云端客户端也无法通过它自己的 `127.0.0.1` 访问你的电脑。完整兼容范围见[通用 MCP 接入说明](docs/MCP_CLIENTS.md)。

### Codex / Claude Code 自动配置（可选）

两个快捷入口会备份并增量合并客户端配置，添加 MCP 服务、全局记忆规则和 SessionStart 摘要 hook，保留其他已有设置。连接前可以预览将修改的文件；客户端要求的重启、MCP 或 hook 信任步骤仍需完成。

Windows 下也可双击 [`Connect-Codex.cmd`](Connect-Codex.cmd) 或 [`Connect-Claude.cmd`](Connect-Claude.cmd)。移除时，在工作台选择 **移除本项目配置**。

手动添加 MCP 与自动配置使用同一份记忆。若希望手动接入的 Agent 自动检索和记录，可将工作台中的 **自动记忆规则** 粘贴到该软件的全局指令中。

### 验证一次跨 Agent 读写

在第一个 Agent 中使用以下示例：

> 请使用 obsidian_shared_memory 记住：示例项目的接口文档使用中文。保存为项目决策，项目名填写“接入测试”。

再在第二个 Agent 的新会话中说：

> 请使用 obsidian_shared_memory 的 recall 工具，查询“接入测试”项目的接口文档语言，并给出记忆标题和来源。

在工作台中确认笔记已经出现。仅显示“服务已添加”不能证明实际读写成功。

也可导入 [`examples/示例记忆包.zip`](examples/示例记忆包.zip) 体验界面，其中的三条笔记均明确标记为示例。

## 跨电脑迁移

**电脑 A 导出 → 传递 ZIP → 电脑 B 预览并导入。**

1. 在电脑 A 的 **导入与导出** 页面导出记忆包。
2. 用 U 盘或自己选择的文件传输方式，把 ZIP 带到电脑 B。
3. 在电脑 B 安装并启动本项目，选择记忆包，预览后确认导入。

| 导入情况 | 处理方式 |
| --- | --- |
| 相同 ID、相同内容 | 跳过，重复导入不会重复创建 |
| 相同 ID 内容不同，或文件名冲突 | 默认保留两份；也可选择保留本地或覆盖 |
| 本地笔记未出现在记忆包中 | 保留本地笔记 |
| 导入过程中失败或中断 | 使用导入前恢复点回滚 |

记忆包包含 Markdown、稳定 ID 和校验清单。**本机历史、回收站、访问令牌、客户端配置和索引不随包迁移。** v1 仅迁移文字笔记，不打包附件，也不改写笔记中的绝对路径与外部链接。

MCP JSON 配置用于添加服务，记忆 ZIP 用于迁移笔记；接入另一个软件不需要重新导入记忆。

## WSL2

推荐保留 Windows 上的记忆服务，让 WSL2 中的 Agent 通过 MCP 访问同一份文件。

| WSL2 网络模式 | 访问当前 Windows 服务 |
| --- | --- |
| 镜像模式 `mirrored` | 可按该网络模式的能力，通过 `http://127.0.0.1:8765/mcp` 连接 |
| 默认 NAT 模式 | 当前不能直接连接，需要额外桥接或适配 |

Windows 11 22H2 及以上支持镜像模式，配置方式见[微软官方 WSL 网络文档](https://learn.microsoft.com/windows/wsl/networking#mirrored-mode-networking)。本项目仅监听 Windows 回环地址，并校验主机名；在 NAT 模式下，仅替换 URL 为 Windows IP 不足以接通。

连接参数需要添加到 **WSL 内实际运行的 Agent** 的设置中。当前尚未完成 WSL 内部的实际 MCP 联通测试，表中说明的是网络与实现条件。

## 记忆如何由你控制

| 操作 | 行为 |
| --- | --- |
| Agent 新增 | 通过 MCP 网关原子写入 Markdown，并记录本机历史 |
| Agent 修改 | 必须提供读取时的版本；过时写入会被拒绝 |
| Obsidian 编辑 | 下次扫描时观察文件变化，并记录可见版本 |
| 工作台或 Agent 删除 | 移到本机回收站，可在设置中恢复 |
| 导入记忆包 | 先预览，再创建恢复点并应用变化 |

程序关闭期间的中间编辑无法全部记录；Obsidian 自己删除的文件由其回收站管理。自动记忆规则可能受到客户端审批或项目级指令影响，是否保存以实际工具返回和落盘笔记为准。

```mermaid
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["本机历史与恢复点"]
```

## 文件与隐私

| 路径 | 内容 |
| --- | --- |
| `MemoryVault/AI-Memory/` 或所选 Vault 的 `AI-Memory/` | 权威 Markdown 笔记 |
| `.local/history.sqlite3` | 本机版本历史与活动 |
| `.local/backups/`、`.local/trash/` | 库恢复点与可恢复删除 |
| `.local/secrets.json`、`.local/config-backups/` | 访问令牌与原客户端配置备份 |
| `.local/basic-memory/` | 索引引擎配置与本地数据 |
| `.runtime/app/`、`.local/engine-env/` | 主程序与引擎各自的 uv 环境 |
| `.runtime/uv-cache/`、`.runtime/python/` | 依赖缓存与按需准备的 Python |

服务仅监听 `127.0.0.1`，MCP 使用本机令牌，工作台 API 校验同源与请求令牌。索引引擎默认关闭语义模型、云模式和自动更新，不额外调用模型 API。

配置备份可能包含原客户端的敏感设置。发布源码时，请保留 `.gitignore`，并将 `.local/`、`.runtime/`、真实记忆库和含令牌的 MCP JSON 留在本机；通过网页上传文件时同样需要排除它们。源码打包脚本会排除运行数据，只附带明确标记的示例记忆。

本项目的文件范围约束不能限制 Agent 自身已有的 shell 或文件访问权限。记忆内容应作为资料使用，不应把笔记中的不可信文本当作执行指令。

## 常见问题

<details>
<summary>保存目录或连接 Agent 时提示权限不足</summary>

确认当前用户可以访问目标目录。由 Agent 沙箱启动的进程可能无法写入工作区外的 Vault 或客户端配置目录，可授权对应目录，或自行打开项目启动脚本后重试。

Windows 的客户端接入也可以使用 `Connect-Codex.cmd` / `Connect-Claude.cmd`。错误弹窗会保留具体原因；自动配置修改前有备份，保存目录失败时保留原记忆库。

</details>

<details>
<summary>MCP 已连接，为什么没有自动保存聊天？</summary>

MCP 提供记忆工具，Agent 决定何时调用。将自动记忆规则加入客户端的全局指令，再检查工具调用和工作台中的实际笔记。项目只鼓励沉淀稳定事实、明确决策与可复用经验，不读取或存档完整聊天记录。

</details>

<details>
<summary>切换 Vault 后，旧笔记在哪里？</summary>

旧笔记仍在原目录。切换只改变活动记忆库，不自动搬迁；如需迁移，可在旧库导出记忆包，再切换到新库并导入。

</details>

<details>
<summary>Basic Memory 没安装，或中文检索没有命中，怎么办？</summary>

基础记忆读写和中文文本匹配不依赖索引引擎。可先使用工作台搜索或 MCP 的 recall 工具，再在设置中安装、重启引擎或查看日志。默认未启用语义模型，不能把文本匹配当作完整的语义检索。

</details>

## 开发

Python **3.12**，依赖由 **uv** 管理。主程序使用根目录的 `pyproject.toml` / `uv.lock`，可选引擎使用 `engine/` 下的独立项目和锁文件。

```sh
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 工具 | 用途 |
| --- | --- |
| `recall` | 检索相关记忆，可按项目筛选 |
| `read_memory` | 读取全文及当前版本 |
| `remember` | 新增记忆 |
| `update_memory` | 使用版本检查更新记忆 |
| `recent_memories` | 查看最近更新 |
| `forget_memory` | 按用户要求将记忆移入回收站 |

测试覆盖并发版本检查、历史恢复、迁移往返、重复导入、冲突处理、失败回滚、路径校验、访问边界和配置合并。跨平台执行定义见 [GitHub Actions 配置](.github/workflows/test.yml)，实际执行结果见[验证记录](docs/VALIDATION.md)。

源码打包入口为 [`tools/build_package.py`](tools/build_package.py)。真实索引引擎测试位于 [`tests/engine_smoke.py`](tests/engine_smoke.py)，需要已安装的固定依赖环境与独立测试数据目录，不应指向真实 Vault。

## 文档

- [通用 MCP 接入与兼容范围](docs/MCP_CLIENTS.md)
- [记忆包格式与导入规则](docs/ARCHIVE_FORMAT.md)
- [测试结果与尚未验证的范围](docs/VALIDATION.md)
- [调研与选型](docs/RESEARCH.md)

## 许可与致谢

本项目集成层采用 [MIT License](LICENSE)。[Basic Memory](https://github.com/basicmachines-co/basic-memory)、[MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk) 和 [uv](https://github.com/astral-sh/uv) 等第三方组件保留各自许可证，见 [THIRD_PARTY.md](THIRD_PARTY.md)。

Obsidian、Codex、Claude Code 是各自厂商的独立产品，本项目与其无隶属关系。