supragnosis

supragnosis

为 AI Agent 提供记得消息来源的记忆。

为编码 Agent 提供共享项目记忆，并保留依据。supragnosis 是一个本地 MCP 服务，可供 Claude Code、Codex、Cursor 和其他 MCP 客户端使用。Agent 在工作时记录所学内容，每条 断言都会保留是谁提出的、代表谁提出、依据是什么，以及当前节点对其信任程度。相互矛盾的 断言会并列保留，供你裁定，而不会让后来的断言覆盖较早的内容。

它专为这样的小团队打造：团队希望在每台机器上都保存一个项目的记忆，并与队友共享， 而无需依赖供应商云服务：一个二进制文件、内嵌存储，无需账户。只有在你列出工作区时， 它才会离开你的机器。

supragnosis = supra (above) + gnosis (knowing) - knowledge about knowledge.

它解决的问题

大多数 Agent 记忆回答的是记住了什么，却不会回答是谁说的。

对于只需记住一位用户偏好的单个助手来说，这没什么问题。但只要有两个 Agent、两台 机器或两个人向同一份记忆中写入内容，情况就不一样了：

• 两个 Agent 提出相反的事实。后写入的内容获胜，分歧也随之消失。
• Agent 将一份被污染的文档总结到记忆中。没有记录其来源，也就无法追踪这份总结还污染了什么内容。
• 你想与队友共享项目知识，却不想共享私人笔记。但存储中没有区分知识归属的概念，因此无从划定边界。
• 凭据进入了日志。你既无法找到它，也无法将其移除。

supragnosis 将断言与事实视为不同的事物。存储的内容绝不是“X 为真”，而是“主机 H 在时间 T， 基于来源 S，提出了 X”。当前信念由策略根据这些断言计算得出，而你可以替换该策略。因此， 改变解决冲突的方式时，只需重新计算，无需改写记录。

它能带来什么

每条断言都有来源信息	操作主机、代表其提出断言的主体、工作区、来源、观察时间、置信度，以及由接收节点计算而非接受对方提供的信任等级
冲突始终可见	相互矛盾的断言会共存，并呈现出来供人调解，而不是被其中一条悄然覆盖
不会销毁任何内容	观察日志只追加写入，并按内容寻址。更正会作为新的观察记录；合并可以撤销
纳入正典前设有审核关卡	实体合并、信任等级提升和架构变更都必须经过提案，并附带一份计算得出的差异，显示裁定将推翻哪些内容
共享由你选择	只有在列出工作区后，它才会离开节点。对等节点按工作区授权，在同步路径和查询路径上都同样如此
秘密不会被写入	检测到凭据特征的文本会在摄取时被拒绝，而不是被改写，因为已经复制出去的只追加日志无法收回
本地优先，无云服务	一个二进制文件、内嵌的纯 Rust 存储、无需账户，也不会联网，除非你配置了对等节点

快速开始

brew tap ashon/tap
brew install supragnosis-server
supragnosis service install         # MCP on :7373 + local viewer, now and at every login
supragnosis connect claude-code     # or claude-desktop, cursor, vscode, codex, gemini, opencode

不带应用参数运行 supragnosis connect 会列出应用，并说明如何连接每个应用。它会向应用注册 supragnosis bridge：这是一个 stdio 服务，会将请求转发给守护进程，并自行从 ~/.supragnosis/mcp.token（权限模式 0600）读取守护进程的 Bearer 令牌，因此应用的设置中不会保存令牌副本。 这样也能连接 Claude Desktop，因为它只接受通过 stdio 连接的本地服务。需要 URL 的客户端可以使用 http://127.0.0.1:7373/mcp 和该令牌；supragnosis status 会打印命令，但从令牌文件读取令牌，不会打印令牌本身。

使用 Claude Code 时，connect 还会注册一个钩子，因此无需主动请求，记忆也会自动填充：Agent 提交代码后，系统会询问它此次更改背后的决策——这是 diff 无法体现的内容；新会话也会一开始就了解该项目工作区中已有的内容。--no-capture 会跳过钩子；钩子本身绝不会写入任何内容（见 docs/client-connect.md 第 12 节）。

使用桌面应用（brew install --cask supragnosis）时，无需打开终端，在设置页面（托盘中的 Settings...，或按 Cmd+,）即可完成这两项操作：开启 Start at Login 可让守护进程持续运行；在 AI apps 中点击一下，即可连接 Claude Desktop、Claude Code 等应用。运行 brew upgrade 后，使用 supragnosis restart 加载新版二进制文件——在此之前，supragnosis status 和托盘都会显示守护进程仍在运行旧版本。

不使用 Homebrew：

curl -fsSL https://supragnosis.dev/install.sh | sh    # ~/.local/bin, checksum-verified
supragnosis service install                           # macOS; Linux: deploy/systemd
supragnosis connect claude-code

检索除了关键词匹配，还支持语义检索：本地嵌入模型支持多种语言，大小为 224 MB，无需 API 调用。service install 会将模型下载到 ~/.supragnosis/models，只需下载一次；也可以手动运行 supragnosis embed fetch 下载。在模型就位之前，检索仅支持关键词匹配，supragnosis status 会说明这一点。工具调用加载模型后，守护进程会占用约 1 GB 内存；设置 SUPRAGNOSIS_EMBED=none 可保持仅关键词检索模式并减少内存占用（见 docs/semantic-retrieval.md）。

卸载时会将守护进程从登录启动项中移除、断开各 AI 应用的连接并删除二进制文件；除非一并删除 ~/.supragnosis，否则知识仍会保留在其中 （见 deploy/README.md, Operations）。

你的第一分钟

用你习惯的措辞，让 Agent 记住一件事：

**你：**记住，这个仓库中的身份验证使用 JWT，有效期为 15 分钟；之所以这样决定，是因为移动客户端无法保存会话 Cookie。

Agent 会调用 observe。记录下来的并不是这句话，而是一条观察记录，其中包含它提到的实体、实体间的关系，以及是谁说的：

observed  "auth in this repo is JWT with a 15-minute expiry..."
          entities   JWT [AuthMechanism], mobile client [Component]
          relations  repo --uses--> JWT,  JWT --constrained_by--> mobile client
          provenance host=your-laptop  on_behalf_of=you  tier=agent_extracted

之后，在一个全新的会话中，且上下文窗口里没有上述内容：

**你：**这里的身份验证是如何实现的？

**Agent：**使用有效期为 15 分钟的 JWT。这是你直接告诉我的，并非我从代码中读到的；你给出的理由是移动客户端无法保存会话 Cookie。

答案的后半部分才是重点。搜索结果会给出匹配项的 ID，而这个 ID 会指向来源信息：get_entity 会列出该实体的所有佐证记录；它所对应的观察记录（supragnosis://observation/{id}）包含原始文本，以及是谁在何时、为谁说了这句话。因此，Agent 能告诉你是谁说的，以及应当有多大把握，你也可以亲自查看。

查看器通过 Unix 套接字与守护进程并行运行——可以通过桌面应用打开，也可以直接读取：

curl -s --unix-socket ~/.supragnosis/viz.sock http://localhost/api/graph

用文字很难传达清楚的，是观察 Agent 工作时的体验：

## Agent 获得什么

13 个 MCP 工具，每个工具对应一种常见意图：

• observe - 自由文本加可选的结构化断言。无需预先定义架构。
• search_knowledge - 关键词检索（每个词都要匹配，顺序不限）加语义检索，并标明使用的模式。
• get_entity、traverse - 精确查找和有界图遍历。
• workspace_map - 共现超边：哪些内容往往会一起被提及。
• define_type - 将一种模式提升为工作区词汇表中的类型。
• propose、review、list_proposals、get_proposal - 通往规范知识库的关口。
• sync_status、sync_pull、sync_push - 联邦同步。

另外还有可解引用的资源：supragnosis://workspaces、 supragnosis://workspace/{ws}/graph、supragnosis://workspace/{ws}/hypergraph、 supragnosis://workspace/{ws}/types、supragnosis://observation/{id}。

你能获得什么

4 个 MCP 提示词，客户端会将它们作为命令提供（在 Claude Code 中为 /mcp__supragnosis__brief）：

• brief - 当前工作区知识的概况：主题、争议内容、仅依据单个 Agent 声明的内容，以及等待你决策的事项。
• what-do-we-know-about - 知识库中关于某个主题的内容、来源，以及缺少的内容。
• curate - 模型会根据整理信号，为需要的清理工作起草提案。
• review-proposal - 对某个提案进行初步审查：合并它会带来哪些变化，以及给出的建议。

你的模型会根据当前状态撰写概况，不会存储任何内容。值得保留的判断会成为提案，而你可以在应用的 Review 面板中作出裁决。留下来的就是规范知识库，下一份概况会据此生成。参见 docs/prompts.md。

工作原理

三个理念，其余一切都由此而来。

事件溯源。 不可变且基于内容寻址的观测是真实数据源。实体和关系图是一个投影，可以丢弃并通过重放日志重新构建。更改解析策略只需重新投影，而不必迁移。

与拓扑无关的收敛。 持有相同观测集合的节点会生成相同的图，无论事件经过何种路径、按何种顺序到达。内容寻址负责去重，混合逻辑时钟负责排序，投影则是确定性的折叠过程。本地运行、中心辐射式、直接对等或混合模式：拓扑是运维选择，而非语义选择。

六边形端口。 领域 crate 不依赖任何 IO。存储、嵌入器和传输都通过端口接入，并接受同一套一致性测试。这不是空谈：我们新增了第三种存储适配器，并删除了原有后端；虽然采用了不同的查询范式和存储引擎，却没有改动 core 或 engine 中的任何代码。

文档

architecture.md	构建了什么、如何构建，以及第 14 节：对未实现内容的如实记录
principles.md	规范性文档。每项设计决策都要依据它说明理由
federation.md	节点身份、同步协议、信任评估
proposal-workflow.md	通往规范知识库的关口
resolution.md	断言如何转化为当前信念
excision.md	移除知识的唯一操作，以及为何它是最后一步
consolidation.md	如何在不删除任何内容的情况下保持工作区整洁
CONTRIBUTING.md	如何构建、测试并提交更改

状态

目前已实现：混合检索、呈现争议主张的信念解析、带有可撤销实体合并门控的身份解析、通过 TLS 复制由中心辐射式拓扑组成的日志（事件使用 ed25519 签名），以及实时查看器。

尚未实现：双时态时光查询、多主体治理、检索降级和空闲整合，以及自动类型归纳。

第二份清单不是随手列出的路线图。每项未满足的需求都是一条具名条款，声明了其证据状态，并由 principle_coverage.rs 测试；每项延期都注明了将兑现它的里程碑。如果某项防护被删除或重命名，相应条款就会报告自己未受防护。参见 architecture.md 第 14 节。

兼容性。 存储绝不会被误读。新版本会原地升级由更早版本写入的存储。对于被更晚版本改动过的存储，新版本会拒绝使用，且不会对其作任何更改：消息会指出应安装的版本。ID 或签名一经生成，在之后的所有构建版本中都能通过验证。1.0 之前的次要版本可能会提高存储所需的版本，其发行说明会提前说明。CLI 的 --json 响应包含架构版本号。MCP 工具的破坏性变更会列在破坏性变更中。完整承诺，以及它为联邦设计（同步线路）留下的部分，详见 docs/compatibility.md。

配置

所有配置项都有可用的默认值。完整配置项请运行 supragnosis --help 查看；默认值背后的设计依据请参见 docs/architecture.md。

最常用的配置项：

• SUPRAGNOSIS_WORKSPACE - 默认工作区（默认值为 default）
• SUPRAGNOSIS_DATA_DIR - 存储目录（默认值为 ~/.supragnosis/redb）
• SUPRAGNOSIS_EMBED - fastembed（默认值）| hashing | none。none 仅支持关键词
• SUPRAGNOSIS_EMBED_MODEL - multilingual（默认值）| bge-small-en（仅英语，体积减半）
• SUPRAGNOSIS_CONFIG - supragnosis.toml 的路径。不提供文件表示使用独立节点
• SUPRAGNOSIS_MCP_AUTH - on（默认值）| off。off 会关闭守护进程的 bearer 校验

MCP HTTP 守护进程仅绑定回环地址，并且需要 bearer token。这是两项不同的防护，因为回环地址所解决的问题与人们的想法不同：它将服务范围限制在这台主机上，而不是某个用户，因此在共享机器上，否则任何本地账户都可能通过它执行 observe、review 和 sync_push。token（~/.supragnosis/mcp.token，权限模式为 0600）用于确保只有你能访问该服务；查看器通过其套接字文件实现的访问控制也相同。查看器可以改用 unix 套接字，但守护进程不能，因为 MCP 客户端使用 HTTP 通信。

查看器完全不使用 TCP 端口：它通过 unix 套接字提供服务，套接字的 0600 权限模式就是访问控制，并且每个响应都带有 Content-Security-Policy。联邦服务若绑定非回环地址，则必须启用 TLS，并且至少有一个已准入的节点或有效邀请；否则服务会拒绝启动。

第二台机器通过代码加入：在作为中心节点的机器上运行 supragnosis invite，在另一台机器上运行 supragnosis join（见 docs/pairing.md）。两台机器各自保留守护进程，并进行同步。

从早于 0.2 的存储升级

截至 v0.1.21，存储使用 Cozo。本构建版本仅读取 redb；如果旁边存在尚未迁移的 Cozo 存储，它会拒绝启动，而不会在该存储旁边启动一个空实例。请先阅读 docs/store-migration.md 第 5 节，然后：

supragnosis stop
curl -fsSL https://supragnosis.dev/install.sh | sh -s -- --version v0.1.21
supragnosis migrate-store
curl -fsSL https://supragnosis.dev/install.sh | sh
supragnosis start

许可证

MIT OR Apache-2.0，由你选择。参见 LICENSE-MIT 和 LICENSE-APACHE。

除非你另有说明，否则你有意提交以供纳入的任何贡献均按上述双重许可授权，且不附加任何条款。