企业官网建设流程全解析

obsidian-wiki如何把Vault变成多Agent共享的记忆服务？Docker+MCP部署完整教程

【免费下载链接】obsidian-wikiFramework for AI agents to build and maintain a digital brain through Obsidian wiki | Memory System for Agents项目地址: https://gitcode.com/gh_mirrors/obs/obsidian-wiki

obsidian-wiki是一个让 AI Agent 通过 Obsidian Wiki 构建和维护"数字大脑"的框架，也即Memory System for Agents（Agent 记忆系统）。本文介绍如何用Docker + MCP把它部署成一个多 Agent 共享的记忆服务：一个容器、一个 Vault、一个 API Key，远端的 Agent 就能通过 HTTP 或 MCP 搜索、读写这份记忆。🧠

为什么你的多个 Agent 需要一座共享的"记忆服务"

你是否遇到过这种情况：周二在一个项目里解决了某个难题，三个月后在另一个项目里又从零开始——因为答案躺在某个再也翻不到的聊天记录里。

本地安装的 obsidian-wiki 解决了"一个人 + 一个 Agent"的记忆问题，但当你有多个 Agent 分布在不同机器（开发机、CI、云端 Agent）时，就需要把 Vault 放到一个 URL 后面，让它们都能搜索和写入同一份记忆。

这正是 docs/deployment.md 描述的场景：把 Vault 装进容器，背后是一个挂载卷上的纯 Markdown 目录——你仍然可以用 Obsidian 直接打开它。

部署前的核心设计：为什么多 Agent 并发写入也安全

共享记忆服务最关键的问题是：多个 Agent 同时写，会互相覆盖吗？

obsidian-wiki 的答案是"一个写入者，一把锁"：index.md、log.md、hot.md和_meta/下的 profile、todo 文件，全部走同一条写入路径，加锁后原子替换。无论是 API 写入、技能写入还是批量摄取，都不会丢失更新。

容器本身不做任何 LLM 工作——它只负责搜索、读取、写入和打包上下文，思考由调用方的 Agent 完成。这让镜像又小又稳。

Docker 部署教程：3 步启动记忆服务

第 1 步：获取仓库

git clone https://gitcode.com/gh_mirrors/obs/obsidian-wiki cd obsidian-wiki

第 2 步：生成 API Key

服务没有默认密钥，缺失WIKI_API_KEY时进程会拒绝启动（本地开发可设WIKI_ALLOW_ANONYMOUS=1临时关闭鉴权）：

echo "WIKI_API_KEY=$(openssl rand -hex 24)" > .env

第 3 步：构建并启动

docker compose up --build

docker-compose.yml 已预置好端口映射（8080）、密钥注入和名为wiki-data的数据卷；Dockerfile 基于python:3.12-slim，以非 root 用户运行，并内置了每 30 秒一次的/health健康检查。

启动后验证一下：

curl localhost:8080/health # -> {"ok": true, "vault": "/vault"}

想复用已有的 Vault？把 compose 里的命名卷换成绑定挂载即可：

volumes: - /path/to/your/vault:/vault

不想用 Docker？本地直接跑也可以：

pip install 'obsidian-wiki[server]' WIKI_API_KEY=dev OBSIDIAN_VAULT_PATH=~/vault python -m obsidian_wiki.server

MCP 接入：让 Agent 一句话连接记忆服务

服务在/mcp路径上挂载了一个 MCP Server，暴露8 个工具，分两组：

以 Claude Code 为例，一条命令完成接入：

claude mcp add --transport http wiki-memory http://localhost:8080/mcp/ \ --header "Authorization: Bearer $WIKI_API_KEY"

其他支持 MCP 的 Agent（Cursor、Codex、Windsurf 等）按同样思路配置/mcp端点和 Bearer 头即可。

多 Agent 共享一份大脑：user_id 命名空间

memory_recap、memory_profile、memory_todo都接受user_id参数：它把某个人的 profile 和 todo 列表隔开，让一次部署服务多个人/多个 Agent，而知识页面保持共享。

user_id会被当作文件名使用，因此服务会严格校验（1–64 位字母、数字、.、_、-），非法值直接返回 400，杜绝文件系统注入。

💡memory_recap是会话开始时最该调用的工具——它把档案、开放线程、近期活动合并成单个文本块返回，可选按project限定范围。

REST API 与运维控制台

除了 MCP，服务还提供完整的 REST 接口（/v1/*均需要Authorization: Bearer <key>）：

• GET /v1/search?q=&limit=— 与wiki-query技能同源的 GraphRAG 搜索
• GET/POST /v1/pages— 按路径读页 / 写入页面
• POST /v1/context-pack— 主题上下文打包
• GET/POST /v1/memory/*— 与 MCP 工具一一对应的记忆端点

API 写入会落到<category>/<slug>.md，带完整 frontmatter，并通过共享记忆写入者追加一行log.md——一次 API 写入和一次技能写入享有同等的加锁与可解析性。写入后记得调POST /v1/memory/sync，把新页面折进index.md和hot.md。

浏览器打开/ui还能得到一个只读运维控制台：页面统计、摄取来源、git 状态、lint 报告，全部实时从磁盘派生，不引入第二份状态。实现见 obsidian_wiki/server.py。

接入已有 Vault？先跑一次 memory migrate

如果你的 Vault 早于"记忆写入器"存在（即文件没有generated_by标记），memory_sync会返回409而不是覆盖你精心维护的文件。这时对挂载的 Vault 执行一次迁移：

obsidian-wiki memory migrate # 预览，不改动任何东西 obsidian-wiki memory migrate --apply # 备份到 _archives/ 后正式接入

迁移会先写带时间戳的备份，保留你手写的所有章节，把"Active Threads"解析成 todo 条目。细节见 docs/memory.md。

备份与安全边界

• 备份：Vault 就是一个目录，像备份目录一样备份——aws s3 sync同步到 S3，或配置 git 远端后用obsidian-wiki sync。
• 安全边界要心里有数：这是单租户设计——一个容器、一个 Vault、一个 Key。user_id只是记忆层面的命名空间，不是权限隔离；拿到 Key 的人可读任何范围。服务间没有配额、限流和计费；要给多人服务，请每个 Vault 一个容器 + 反向代理终结 TLS（容器本身只说 HTTP，Key 的安全性取决于承载它的连接）。

小结

至此，你的 Obsidian Vault 不再只是本地笔记，而是一个多 Agent 可搜索、可读写、锁保护的共享记忆服务——Markdown 在磁盘上，随时可读、可 grep、可 diff，没有任何锁定。完整配置变量参考 docs/configuration.md，全部子命令见 docs/cli.md。🚀

【免费下载链接】obsidian-wikiFramework for AI agents to build and maintain a digital brain through Obsidian wiki | Memory System for Agents项目地址: https://gitcode.com/gh_mirrors/obs/obsidian-wiki