knowledge

knowledge

一款小型、可自托管的知识服务，为 AI 编码 Agent 提供支持。它让每台设备上的 Claude Code、Codex 和 Antigravity（agy）都能通过 MCP 使用同一套实时文档和记忆，并提供一个展示笔记关联关系图谱的 Web UI。

笔记是磁盘上的纯 Markdown 文件。服务会为它们建立索引，通过每台设备专属的令牌将笔记提供给 Agent，并依据几条内部规则检查笔记，让不断增长的 Agent 记忆库始终易于查找且井然有序。

_{来自 demo/ 的虚构演示笔记；使用 uv run --project server --with playwright python demo/screenshot.py 重新生成。}

功能

• **面向 Agent 的 MCP 工具：**搜索（正则和语义）、读取、列出、相关笔记、写入和编辑（带冲突检查）、新建备忘录、删除（保留为副本）、历史记录、lint，以及将网页、PDF 或文本作为原始来源导入。
• **会话启动上下文：**每个 Agent 都会获取共享说明、项目规则，以及其所处理项目的记忆索引；还会获取日期已过的未完成事项，以及 Agent 之间的交接任务。
• **会话中的交接：**在提示词前（最多每两分钟一次），Claude Code、Codex 和 agy 会调用 /tasks 获取分配给它们的任务；会话开始后添加的任务会通知 Agent 一次。同一个逐轮调用还能让服务端引导每个会话，包括未运行启动钩子的恢复会话：通知（例如文档已移入归档文件夹）会发送给设备上第一个发起请求的会话；如果该会话一小时内没有后续轮次，就会再次发送。当设备上次完整同步文档镜像的时间距今超过 docs_sync_minutes（管理页面中的 Settings）时，还会要求一个会话在后台运行完整同步。
• **唤醒另一个 Agent（同一台机器）：**执行 knowledge_edit/knowledge_write/knowledge_new_memo 后，插件会唤醒这台机器上每个 Agent 和项目中最新的、空闲且有新任务的会话：Codex 使用 codex queue --thread，agy 使用其本地语言服务器（agy 会话通过运行终端命令 agent_hooks.py register 注册一次；插件会提示它注册），Claude Code 则使用 asyncRewake 等待钩子。被唤醒的 Agent 会告知用户并等待同意。管理页面会按 token 列出过去一周内出现过的会话（Agent、会话 ID、项目、是否可唤醒），每项都有一个 Forget 按钮。
• **用量限制：**每次提示词都会检查 Agent 自身用量限额的使用情况，并在每个会话和限额时段内，于 50%、75% 和 90% 时各提示一次；从 95% 起将拒绝创建新的子 Agent（Claude Code Agent、Codex spawn_agent、agy invoke_subagent）。这些数字来自 Agent 自身：Codex 的 rollout、agy 的语言服务器（注册一次后），以及 Claude Code 的用量信息；Claude Code 只会将这些信息提供给状态行，因此插件会在会话开始时将一个小型转发器放在你的状态行前面（你的状态行仍会显示；旧命令保存在 ~/.knowledge/statusline-original.json 中）。没有用量数字时，不会提示或拒绝。
• **机密保护：**如果编辑操作要将已知机密值写入文件，就会被拒绝（Claude Code Edit/Write、Codex apply_patch、agy 文件工具）；token.py push-secrets 会留下哈希文件。只有新增文本会被检查，因此允许删除机密。
• **Token 用量：**会话日志还会发送每个已记录部分的 token 数（未缓存输入、缓存写入、缓存读取、输出；Claude 的同一次调用按块复制只计一次，Codex 的累计总数则通过差值计算）。Lint 会报告 usage_outlier：过去一周中用量远高于该 Agent 常态的会话（基于过去一个月的数据，至少 10 个会话时计算修正 z 分数，阈值为 3.5）。
• **项目：**每个项目都有文档根目录和记忆根目录。会话根据工作文件夹选择项目；也可以将 token 限定到一个项目（访客）。新服务默认只有一个项目（homelab，文档位于 data/docs，记忆位于 data/memory）；管理页面可以创建更多项目，并为项目指定 Web UI 中显示的名称。
• **Lint：**确定性检查，约 80 ms 即可完成：失效链接、索引中没有对应文件的条目及其反向情况、缺少 frontmatter 或章节、备忘录过大、逾期未完成事项、可能的机密（绝不显示），以及尚未处理的原始来源。
• **Web UI：**按主题显示的主页、完整搜索、带关联笔记的笔记预览、编辑器、更改历史、lint 选项卡，以及用于管理 token、人员和项目的管理页面。可选择浅色或深色主题。
• **图谱：**笔记作为节点，链接作为连线；每个主题形成一个连通区域。连线的粗细和拉力取决于两篇笔记的关联程度（直接链接、共享来源、共享邻居、类型相同）；主题间的弱关联会在悬停时显示。
• **外部技能：**管理员通过链接从 GitHub 添加技能文件夹；技能会固定到某个提交，只以纯文本形式引入（不含工具、钩子或加载时命令，且许可证允许复制），并像自有技能一样共享。每周会自动引入小型更新，并将大型或不安全的更新暂存，等待管理员处理；`` 下的本地新增内容在更新后仍会保留。
• **归档：**搜索会跳过 archief/、archive/、old/ 或 history/ 等文件夹，除非明确要求搜索。
• **离线副本：**拥有写入 token 的设备会保存一份记忆副本，并且只同步差异；服务端宕机时，Agent 仍能获取缓存的启动上下文。
• **机密：**所有回复都会屏蔽已知机密值，所有写入都会拒绝包含这些值的内容。

工作原理

• 服务端（server/）：使用 Python，在一个 Docker 容器中运行无状态的流式 HTTP MCP 和 Web UI。所有文本都存放在内存中，因此搜索几千个文件只需几十毫秒。监视器会发送发生变化的路径，以便立即更新；每 60 s 进行一次仅检查文件状态的重新扫描，作为安全保障。嵌入（用于语义搜索和相关笔记）通过 ONNX 在本地运行；数据不会离开设备。
• 客户端（plugin/）：一个可安装为 Claude Code、Codex 和 agy 插件的文件夹。它会添加 MCP 服务、会话启动钩子、会话日志，以及面向访客项目的文档镜像。Codex 和 agy 通过一个小型 stdio 中继连接服务端，因此令牌不会存放在配置文件中。clients/knowledge-agent.py 会完成所有设置。
• **令牌：**每台设备一个长随机令牌，保存在操作系统密钥环中（Linux Secret Service、macOS Keychain、Windows Credential Manager）。令牌可以设为只读、屏蔽、限制到单个项目，或允许同步共享技能。
• **Web 登录：**一个管理员的密码（KNOWLEDGE_UI_PASSWORD，使用有效期为 30 天的签名 Cookie；每分钟最多输错五次），或者供多人使用的带转发身份验证的反向代理（例如 Authentik），由其设置用户标头和共享密钥（KNOWLEDGE_PROXY_SECRET）。

运行服务端

使用 Docker，所有笔记都存放在 compose.yaml 旁边的 ./data 中：

git clone https://github.com/To0wnn/knowledge && cd knowledge
mkdir data && echo "KNOWLEDGE_UI_PASSWORD=<a long password>" > .env
docker compose up -d

打开 http://localhost:8766/ui，使用密码登录，并在管理页面创建设备令牌。笔记存放在 data/memory（包含其 MEMORY.md 索引的备忘录）、data/docs 和 data/shared（与每个 Agent 共享的 CLAUDE.md、规则和技能）中；可以在管理页面创建更多项目。要从其他设备访问：将其 host:port 添加到 .env 中的 KNOWLEDGE_ALLOWED_HOSTS（更改 KNOWLEDGE_PORT 时也要这样做），并在前面配置支持 HTTPS 的反向代理：通过普通 HTTP 传输时，密码和令牌会以可读形式在网络中传输。容器以 uid 1000 运行；如果 ./data 属于其他用户，请在 .env 中设置 KNOWLEDGE_UID 和 KNOWLEDGE_GID。该镜像（ghcr.io/to0wnn/knowledge，包含嵌入模型时约 1.5 GB）会在每次发布时构建； 也列在 MCP 注册表中，名称为 io.github.To0wnn/knowledge。

.env 中的设置（均为可选）：KNOWLEDGE_PUBLIC_URL（用户使用的地址，会写入 Agent 的指令中）、KNOWLEDGE_LANGUAGE（en 或 nl：备忘录的章节为 ## Status 和 ## Decisions，或 ## Stand 和 ## Keuzes；两种格式始终都受支持）、TZ。每个 Agent 获取的规则默认为 default_house_rules.md，直到你在 data/shared 中放入自己的 house_rules.md。

要求：Docker 和约 2 GB RAM（嵌入模型为 1.2 GB，已包含在镜像中，运行时不会下载任何内容）。

原始安装的运行方式不同（server/compose.yaml：通过 NFS 共享笔记，文件来自 Agent 运行所在的机器；部署时无停机切换；KNOWLEDGE_BUILTIN_PROJECTS=homelab,anpitek,trade）：将 local.env.example 复制为 local.env，将卷指向你的文件夹，然后运行 ./deploy.sh。该脚本会运行测试、将 server/ 复制到 Docker 主机、构建、切换，并等待 /health。

连接客户端

服务器的帮助页面（/ui/help）列出了每种客户端和操作系统的具体步骤。简而言之：

curl -fsSL https://raw.githubusercontent.com/To0wnn/knowledge/main/install.sh | sh   # Linux, macOS

irm https://raw.githubusercontent.com/To0wnn/knowledge/main/install.ps1 | iex        # Windows

两者都需要 git 和 Python 3.9 或更高版本（macOS 自带的 python3 是 3.9）。它们会将脚本保存在 ~/knowledge 中（这是一个 git 检出；即使历史记录被重写，也会将其恢复），并运行 clients/knowledge-agent.py setup。每次运行的流程都相同：首次运行时，它会找到 Claude Code、Codex 和 agy，并逐一询问是否安装（y/n）；此后，它会更新已安装插件的 Agent；对于检测到但尚未安装插件的 Agent，只询问是否安装（y/n）；只有当服务器拒绝已保存的令牌时，才会询问令牌。

install claude（或 codex、agy）会设置一个 Agent，不会询问要设置哪些。install 会询问服务器地址（也可以设置 KNOWLEDGE_URL，例如 KNOWLEDGE_URL=http://localhost:8766，仅对本次运行生效）；安装程序没有默认地址，因此令牌绝不会发送到未指定的服务器。 响应的服务器地址会保存到 ~/.config/knowledge/url，供所有 Agent 的钩子使用，并设为 Claude 插件的“Knowledge server URL”选项，因此后续会话和 update 无需其他设置。

安装程序只会询问一次令牌，用它向服务器进行验证，将其存入密钥环并安装插件。插件会在每个 Agent 中自动保持最新，并在会话开始时提示一次：在 Claude Code 中，它会启用市场的自动更新功能（可在 /plugin > Marketplaces 下关闭）；Codex 和 agy 不支持插件自动更新，因此插件每天最多检查一次 GitHub，并使用 Agent 自带的 CLI 更新（未安装插件时的设置流程：将 git 检出更新到 GitHub 的 main；如果历史记录被重写但内容没有变化，也会执行此操作，然后再次运行设置流程；手动运行 knowledge-agent.py update 也会执行相同操作）。关闭自动更新：KNOWLEDGE_AUTO_UPDATE=0。新版本会在下次启动时加载。每次会话启动时都会报告插件版本：管理页面会按设备和 Agent 显示版本；如果设备上的版本在两天后仍落后于最新版本，插件会提示如何手动更新（lint 中也会列为 plugin_behind）。

将项目文件夹关联到对应项目只需设置一次：让 Agent 执行（技能 knowledge-init），它会在文件夹根目录中写入一个包含项目名称的 .knowledge-project 文件。在该文件夹中启动的每个会话都会使用此项目。关联的 git 工作树（Codex 和 agy 会为每次聊天创建一个）会被视为主检出：项目相同，文档只从主检出镜像同步（该文件夹是来源：与 UI 一样，knowledge_write/edit/delete 会拒绝修改镜像，因为下次同步会撤销这些更改）；会话也会获知自己运行在单独的检出中。在 Windows 上，agy 需要 PATH 中有 python3 命令（python.org 安装管理器或 Microsoft Store 中的 Python 都会提供该命令）；如果没有，设置流程会为 agy 配置但不安装插件。Windows 上的 Codex 和 agy 钩子会通过 plugin/python3.cmd 启动 Python：依次尝试 py 启动器、PATH 中的 Python，再尝试注册表中的任意安装（PEP 514），每种方式都会先进行测试运行，因此会跳过 Microsoft Store 的存根；即使没有 py 启动器或 PATH 配置，python.org 安装的 Python 也能正常运行。

该插件还附带开发技能，在每个 Agent 中都相同：plan-change、debug-root-cause、verify-done、 review-diff、project-setup、efficiency-pass、knowledge-init、verified-goal（持续工作，直到检查命令证明任务已完成；每个 Agent 都设有硬性上限和无人值守循环操作指南）以及 fan-out-verify（将范围广泛的工作分配给子 Agent，让每项发现都由新的验证器进行反驳，只报告经验证后仍然成立的内容）。

开发

• server/graph.py、server/lint.py 和 server/vectors.py 在 __main__ 下包含自检；server/test_server.py 用于测试服务端。deploy.sh 会先运行所有这些测试。
• tests/clients_e2e.py 使用真实服务端运行客户端测试：插件钩子、安装程序、Codex 自行启动 MCP 服务、离线副本和技能同步。每次推送时，CI 都会在 Windows、macOS 和 Linux 上运行该测试 （.github/workflows/clients.yml）。
• tests/ui_smoke.py 使用 Playwright 检查 Web UI。
• 修改插件时，需要更新 plugin/.claude-plugin/plugin.json 和 plugin/.codex-plugin/plugin.json 中的版本号（测试会检查两者是否一致），否则已安装的副本永远不会更新。

浏览器库及其许可证均随附于 server/static/vendor/（force-graph、marked、DOMPurify）；不使用 CDN。

许可证

MIT，详见 LICENSE。