gosidian

gosidian

AI Agent 可以通过 MCP 读取、编写和推理的 Markdown 笔记。

一个自包含的 Markdown 库，内置 MCP 服务。人类通过 Web UI 编辑，Agent 通过 MCP 与之交互，所有内容都存储为纯 .md 文件，Obsidian（以及其他所有 Markdown 工具）都能原生读取。

已收录于 官方 MCP Registry，名称为 io.github.daniele-chiappa/gosidian， Glama 和 mcpservers.org

在浏览器中试用

在 GitHub Codespaces 中启动一个免费的临时 gosidian——无需安装，占用你自己的 Codespaces 配额。它会从源代码构建，填充一个小型演示库，并打开 Web UI。使用 demo / gosidian-demo 登录。

快速开始

docker run -d --name gosidian \
  -p 8080:8080 \
  -v "$(pwd)/vault:/vault" \
  ghcr.io/daniele-chiappa/gosidian:latest
# open http://localhost:8080, create admin, copy the MCP token from /admin/tokens
claude mcp add gosidian http://localhost:8080/mcp \
  --transport http --header "Authorization: Bearer $TOKEN"

三条命令：启动 Docker → 在 Web UI 中创建令牌 → 配置 Agent。你的 .md 库会持久保存在 ./vault/ 下；停止容器后，文件仍会保留。

其他安装方式（从源代码安装、自定义 compose、裸机安装）： docs/getting-started.md。

什么是 gosidian

• 一个 Markdown 库。 笔记是磁盘上的 .md 文件。你可以用 Obsidian、VS Code、vim 或任何常用编辑器打开同一个文件夹。没有任何锁定：删除 .gosidian/，你就拥有一个纯粹的 Obsidian 库。
• 一个 MCP 服务。 71 个类型化工具，支持 Agent 初始化会话、导入文件、搜索、读取、编写、链接、交接、自检和审计。使用 Bearer 令牌和 OAuth 授权，并在每次请求时根据账户权限限制其可读写内容。
• 一个 Web UI。 Vue 3 单页应用由同一个二进制文件提供服务（使用 Vite 构建，通过 go:embed 嵌入）。笔记、图谱、搜索和配置表单以窗口形式显示在平铺式「plancia」工作区中——提供全文搜索、反向链接、图谱视图、实时预览编辑器、审计记录，以及用于管理令牌和用户的管理页面。

三种视图都访问磁盘上的同一批文件。SQLite FTS5 索引只是缓存——删除后会自动重建。

适用对象

• AI 工程师：为需要持久化结构化记忆的 Agent 配置工作流，包括笔记、计划、技能、ADR、交接和审计。
• Obsidian 用户：希望在已信赖的库之上添加可编程层的用户。
• 团队：共享一个库，按项目设置可见性，并向账户和团队授予权限；限制新账户的访问，为其指定专属项目；为每个 Agent 提供自助令牌，权限不会超出其所有者。

为什么选择 gosidian，而不是 X

• 与 RAG / 向量搜索相比：gosidian 根据 Agent 的身份（路径、标签、frontmatter、反向链接）检索记忆——对于 Agent 的工作记忆而言，这比相似度搜索更可预测。对笔记进行语义搜索暂缓实现：参见 ADR-007 的理由。针对项目文档（手册、报告、扫描件）的 RAG 则是另一回事，也是 gosidian 的实验性功能之一。
• 与 Obsidian Sync 相比：Sync 会在不同的人类设备间同步一个库。gosidian 则为同一个库添加了类型化自动化接口（MCP）。两者并不竞争，而是互为补充。
• 与 Notion / Roam 相比：它们使用托管式或专有格式，迁移需要专门规划。gosidian 的库已经是 .md 文件，可以随处携带。

详见常见问题。

与类似项目的比较

“Markdown 知识库 + Agent”领域竞争激烈。截至 2026 年 9 月，gosidian 的定位如下：

如果你在关注……	这些项目的功能	gosidian 的不同之处
Obsidian MCP 桥接工具 — mcp-obsidian、obsidian-local-rest-api，以及 Obsidian CLI 的封装	通过 MCP 将正在运行的 Obsidian 桌面应用提供给 Agent。	无头服务：无需运行 Obsidian，可在主机或容器中运行；支持具有角色、按项目设置可见性和授权（账户与团队）的多用户模式；令牌权限按账户收窄；提供审计记录。知识库仍是普通的 Obsidian 知识库。
Markdown 记忆服务 — basic-memory、mcp-vault	同样采用“文件，而非数据库”的思路；通常会添加混合语义搜索、云服务层或 WebDAV 同步。	提供完整的 Web UI、真正的多用户模式、Agent 交接总线，以及由服务提供的工作方法（版本化指令、lint 检查、过时检测）。按设计不提供语义搜索（ADR-007），也没有托管服务层。
客户端 Wiki 技能 — obsidian-wiki 和“LLM Wiki”模式	通过斜杠命令让 Agent 在本地编译和维护 Wiki。没有服务、身份验证或 UI。	将相同模式实现在服务端，且不依赖特定 Agent：一次调用即可搭建框架，在启动时提供指令，并支持交接和审计。两者互补：这些技能也能用于 gosidian 知识库。
Agent 记忆服务 — mem0、agentmemory、mcp-memory-service	将记忆作为不透明存储：嵌入、召回基准测试、自动捕获钩子。	记忆以 Markdown 形式呈现，人们可以在 Obsidian 或 Web UI 中阅读；按身份和图谱检索，不使用嵌入；只有你启用的管道才会调用语言模型。通过 Claude Code 钩子自动捕获（contrib/claude-code/：在会话开始时注入焦点信息，在压缩和结束时生成会话摘要），而非在二进制程序内部实现。目前尚未公布召回数据。
带社区 MCP 服务的笔记应用 — SilverBullet、Trilium、SiYuan	成熟的编辑器、移动应用，有时还支持实时协作；通过第三方服务在其 API 之上添加 MCP。	MCP 优先：服务集成在二进制程序中，与 UI 共用相同的登录、角色和审计机制。没有移动应用、实时协作或所见即所得编辑器。

坦诚来说，目前的不足按常见程度排列如下：笔记的语义／混合搜索（暂缓，参见 FAQ；文档支持实验性的 RAG）、git 以外的移动同步、实时协作，以及托管服务。路线图说明了其中哪些已列入计划。

功能亮点

• 单一二进制文件，≤50 MB，基于 Alpine 的 Docker 镜像
• Web UI：Vue 3 SPA（Vite、Pinia、Tailwind、CodeMirror、Cytoscape）， 嵌入二进制文件中 — 编辑器 + 实时预览、侧边栏、搜索、 图谱视图、附件、审计日志、管理页面
• Plancia 平铺式窗口管理器（niri 风格）：笔记、图谱、搜索 和配置表单会作为可调整大小的并排窗口打开，位于可水平滚动的工作区中， 并可从 URL 恢复
• 基于 Streamable HTTP 的 MCP 服务（保留旧版 HTTP+SSE），包含 71 个类型化工具
• 带作用域（read / write）和按项目限制的 Bearer 令牌 — 包括供编排器使用的多项目令牌； 每次请求时，账户持有的每个令牌都会被限制为该账户可读写的范围，账户可自行创建令牌（inherit 会继承其访问权限，custom 会固定为一个子集），禁用用户时级联撤销
• Agent 编排总线：交接笔记具有原子化的认领 / 完成生命周期、由服务端盖章的身份，以及 memory_wait_changes 长轮询变更流 — 一个极简的多 Agent 任务队列，所有内容都保持为纯 Markdown
• 多用户 Web 登录，角色（Admin / User / Read-only）设定权限上限；按项目设置可见性（private / internal / public）以控制读取权限，并通过向账户和 团队授予授权（read / write / admin）来控制其他所有权限，且可委派给项目管理员；新账户默认受限，并拥有一个个人项目； 仅限邀请注册（24h TTL）
• 可选的 TOTP 双重验证（全局模式 + 按用户覆盖）以及支持访客自动配置账户的 LDAP / Active Directory 登录
• 可选择启用 OAuth 2.1 授权服务器，让 claude.ai / Claude Desktop 自定义连接器、ChatGPT 连接器和 Claude Code 的浏览器登录通过同意屏幕获取各自的令牌 — 无需粘贴 Bearer 令牌
• Claude Code hooks (contrib/claude-code/)： 每次会话开始时注入项目的 hot.md 关注内容，在上下文压缩时和会话结束时将会话摘要追加到知识库 — 不使用大模型，通过 POST /mcp/append 完成，绝不阻塞会话
• 可选 Git 同步（延迟提交，使用令牌认证推送）
• SQLite FTS5 全文搜索 + ETag 乐观锁
• 一流的 .html 笔记，使用沙箱 iframe 渲染（默认关闭，可按项目选择启用）
• 基于维基链接图谱的图分析：memory_hubs（链接最多的笔记）和 memory_path（两篇笔记之间的最短路径）
• 可选择启用自我改进循环：Agent 按令牌记录使用摩擦问题，默认关闭
• 可直接从 Web UI 打印 / 将任意 Markdown 笔记另存为 PDF
• 国际化（IT + EN 已完成；ES / FR / DE 脚手架）
• 浅色和深色主题预设（Catppuccin、Tokyo Night、Solarized）+ 自定义调色板
• 遵循 Karpathy-Wiki-Stack 项目布局，并提供一键脚手架
• 可选的全局项目，用于在项目间共享技能、 Agent 和脚手架模板（可按项目选择启用，本地设置优先于全局设置）

实验性功能：流水线、插件、RAG 和 Agent

这些部分都是新功能，默认关闭，仍在不断变化：设置、节点类型和说明可能会随版本更新而变动，具体变动时间见 docs/upgrading.md。上文介绍的核心功能（知识库、MCP 服务、Web UI）不依赖这些功能；如果安装时保持关闭，就不会接触到它们。

• 流水线（docs/pipelines.md）：一种 type: pipeline 笔记，服务器会在发生某些事件时运行它——收到文件、提交、聊天消息、Agent 或服务的调用，或时钟触发。其节点可以读取和写入笔记、调用语言模型（任何兼容 OpenAI 的端点，无论本地还是远程）、运行脚本，或等待某人的回答。所有流水线共用一个队列，并按插件、提供方和共享资源（例如 GPU）设置限制，在各项目之间公平分配。可通过文本或可视化编辑器编辑。只有设置 [pipelines] enabled = true 并由项目启用后才会运行。
• 插件（docs/plugins.md、gosidian-plugins）：与 gosidian 并行运行的 MCP 服务，每个服务各自位于一个容器中，为流水线添加节点类型，并为 Agent 添加工具。只有所有者接受其清单后，插件才会运行；插件无法访问知识库，只能看到流水线交给它的文件。目前已发布：
  • 文档：docling（将 PDF、办公文件、HTML 转换为 Markdown）、ocr（通过视觉模型处理扫描件）、images；
  • 数据：database（在 PostgreSQL + pgvector、Qdrant 或 SQLite 上存储嵌入向量）、storage（将 Nextcloud、S3 或 Google Drive 用作文件来源）；
  • 人员：chat（可嵌入任何网页的小组件机器人）、notify（Telegram、ntfy、电子邮件，可附带待回答的问题）；
  • Agent 和代码：claude（Claude Code）和 pi（pi.dev）作为执行器，exec（在沙箱中运行脚本）、preview（可通过不易被猜到的地址访问的静态构建）。
• IN 文件夹（docs/in.md）：项目中待处理的文件，以原文件名保存——可通过 Web UI 分块断点续传上传、由 Agent 发送，或从远程存储读取；流水线会将这些文件转换为笔记。
• 针对项目文档的 RAG（docs/chat.md、docs/rag-benchmarks.md）：项目模板 rag 会转换 IN 文件夹中的文件，将笔记切分为段落，连同其嵌入向量一起存储，并基于这些内容回答问题、引用来源；机器人（type: chat）可在独立页面或任何网站的小组件中向它提问。在 ViDoRe V3 的八个公开语料库（14,514 个问题）上使用本地模型进行测量：段落搜索 NDCG@10 为 52.7，评为良好的回答占 57%，每个回答的中位耗时为 5.5 s。Agent 自身的记忆仍按身份检索：RAG 面向文档，而非知识库中的笔记。
• Agent 团队（docs/agents.md）：一种 type: team 笔记，其中定义了团队角色——协调员、写作者、开发者、审查者——每个角色都是由流水线运行的 Agent（通过各自的插件运行 Claude Code 或 pi），负责项目中的笔记任务。gosidian 会分派任务，检查每个 Agent 的改动是否符合其角色对应的路径和检查规则，在合并前征求人员同意，并将成本计入当日预算。试点项目会围绕同一目标反复运行同一个团队：为五个人制定培训计划，并构建一个小型 Web 应用。
• Compose 预设（docs/deployment.md）：deploy/presets/ 可通过一个 .env 文件启动 gosidian 及其 RAG 链（docling、images、基于 Qdrant 的 database 插件、chat）。

文档

类别	从这里开始
安装与配置	入门指南、配置、部署、升级
MCP 集成	概览、工具目录、身份验证、客户端设置、Agent 模式、Claude Code hooks
Web UI	概览、编辑器、身份验证与角色、设置
Vault	格式、约定、多项目、全局项目、Obsidian 兼容性
实验性功能	流水线、插件、IN 文件夹、机器人、Agent 团队、RAG 基准测试
内部文档	架构、开发
常见问题	常见问题解答

完整索引：docs/README.md。

贡献

欢迎贡献。有关工作流、测试要求和翻译指南，请参阅 CONTRIBUTING.md。

安全

安全问题通过私下方式报告。有关披露流程，请参阅 SECURITY.md。

许可证

本项目采用 MIT 许可证 发布。

另请参阅

• PROJECT-STORY.md — 项目起源、设计理念，以及与 Obsidian / Logseq / 基于 RAG 的知识栈的比较。
• CHANGELOG.md — 发布历史。