SurStor Memory

SurStor Memory — 为自行运行的模型提供记忆

网站：www.surstor.net

v0.2.0-alpha.3-mcp.1 · 开发者预览版

当前安装版本：0.2.0-alpha.3-mcp.1，与 官方 MCP 注册表条目一致。 这是 alpha.3 应用的 MCP 打包修订版；捆绑的 JAR 仍报告 0.2.0-alpha.3。它添加了注册表所有权元数据，但不改变应用行为。请参阅发行说明。

用于测试和反馈的早期软件。功能和接口可能会发生变化；存储重要信息前，请先查看下方的限制说明。

根据 Apache License 2.0 授权。第三方依赖项和捆绑资源仍受其各自许可证约束。

将项目决策、有用答案和工作历史保存在自己的硬件上，然后让本地 AI 在不同对话中检索这些内容。SurStor Node（v0.2.0-alpha.3）通过 MCP 提供持久、可检查的外部记忆。模型仍在你选择的推理应用中运行；SurStor 负责存储和检索记忆。

从这里开始：与本地模型一起安装并连接 MCP — 包含 LM Studio 设置、保存与回忆示例，以及 Ollama 集成要求。容器打包请参阅使用 Docker 运行。照常使用你的工具即可。

Local model <-> MCP-capable chat or agent application
                         |
                  SurStor MCP (localhost:8484)
                         |
              Local records + optional search index

• 将经过批准的事实、偏好、决策和交接说明保存为文本记忆。
• 通过本地语义搜索查找相关的过往工作，或按记录 ID 检索。
• 检查来源信息、验证记录完整性，并导出会话以供重复使用。
• 通过兼容的 MCP 主机，让另一个本地模型重复使用同一节点。

SurStor 是一个单用户节点，基于 Covia venues、Convex lattice 和 CAD3 内容寻址构建，不运行 Convex 共识。它绑定到 127.0.0.1:8484。它不会训练你的模型、自动捕获每段对话，也不会自动解决相互冲突的记忆。 主机必须调用其工具。检索少量相关记录可以避免重复提供完整历史；对于你的工作负载，需实际测量令牌节省情况和答案质量。

若要创建全新的加密 venue，请使用加密存储指南 和 config/surstor-encrypted.toml。此可选配置会加密 Etch 记录及其索引，需要外部密钥，并会禁用单独的明文语义搜索索引。现有配置不会自动变为加密配置。

可选的多节点记忆同步

此代码库包含一项可选功能，可在可信节点之间双向同步选定的签名记忆，也支持通过服务中继。每个节点保留自己的身份和加密密钥。请参阅设置、安全性与限制。 在 alpha.3 中提供，并附有可选的 Docker 同步覆盖配置。尚未启用整个 venue 的复制和删除传播。

功能

记忆带有证据链：你可以检索最初保存的内容并检查其完整性。有效签名并不能证明保存的声明属实。请保存简洁、有用的上下文，而不要把所有生成的文本都当作事实。

每个 AI 工作产物（草稿、工具结果、补丁、模型输出）都会存储为一条双单元 CAD3 记录：

• 单元 1——内容，按内容寻址（规范编码的 SHA3-256）
• 单元 2——来源元数据：branch-ref（单元 1 哈希，即 Merkle 绑定）、会话 ID、Agent ID、模型版本、时间戳、令牌用量、版本化费用明细 + 预估成本 + 引用的价格表、prev-event（会话哈希链），以及对未签名单元哈希进行签名的节点 Ed25519 签名

会话构成只追加的哈希链（由 prev-event 关联），因此重写或删除事件都可被检测到。成本在捕获时根据版本化价格表计算，并固定写入记录——历史产物永远不会重新计价。验证时会重放原始计算和价格表。

**成本警告：**SurStor 根据注明日期的公开服务提供商价格快照和调用方提供的用量估算 API 成本。这些并非服务提供商的发票。未报告的费用、税费、抵扣额、订阅费用和协商折扣均不包含在内。无价格记录不计入总额，而是单独统计；旧版会话的覆盖情况可能未知。验证证明的是完整性和计算正确性，而非计费准确性。会话预算并非服务提供商的支出上限。

2026 年 9 月 10 日的快照涵盖 OpenAI、Anthropic、Kimi、Gemini、DeepSeek 和 Grok 的 31 个主流模型条目。新版计费支持缓存写入、缓存存储、工具费用、服务层级、上下文阈值和随时间变化的费率。官方来源、费率、调用方示例、排除项、迁移和验证行为，请参阅**计费与定价文档**。

使用 Docker 运行

现已提供公开的 Linux amd64 镜像：ghcr.io/surstor/surstor-memory:0.2.0-alpha.3-mcp.1。在此检出目录中：

docker compose -f compose.registry.yaml pull
docker compose -f compose.registry.yaml up -d

在 http://127.0.0.1:8484/mcp 连接 MCP。此默认配置文件使用未加密存储和本地语义搜索。有关加密存储和备份指南，请参阅Docker 指南。容器不需要在主机上安装 Java 或 Maven。Docker Desktop 和 ARM64 尚未经测试。

构建和运行

需要 Java 21+ 和 Maven 3.7+。Covia 0.9.6-SNAPSHOT 是默认安装依赖项，由根目录 pom.xml 中的 covia.version 配置。无需覆盖 Maven 版本。

在全新机器上构建 SurStor 前，请检出兼容的 Covia 源代码，并进行构建和安装，以将 ai.covia:covia-core:0.9.6-SNAPSHOT 和 ai.covia:venue:0.9.6-SNAPSHOT 安装到本地 Maven 仓库：

# Run inside the compatible Covia source checkout first.
mvn clean install -DskipTests

然后从 SurStor 仓库根目录运行以下命令。快照版本是默认版本，但无法标识不可变的上游修订版本；请记录所用的 Covia 提交，并针对该构建运行 SurStor 测试。有关依赖项兼容性，请参阅集成说明。

提示词与响应捕获现在提供 /capture 本地审核界面、内置机密检测、组织级排除规则以及失败关闭过滤。记录的内容仅为过滤后的版本。自动检测可能会漏掉敏感数据；保存前请检查每个字段。有关配置、API 用法、兼容性变更和保护限制，请参阅**提示词捕获与隐私**。

mvn package
java -jar surstor-node/target/surstor-node.jar start --config config/surstor.toml

上例使用未加密配置文件。加密安装请遵循加密存储指南。 使用示例配置文件时，节点会将数据持久化到 ~/.surstor-node/（etch 存储 + Ed25519 身份密钥对，首次运行时自动生成）。

其他命令：

java -jar surstor-node.jar status                 # config, identity, budget
java -jar surstor-node.jar verify <bundle.json>   # offline verification of an export bundle

MCP 操作

所有 12 项操作都作为 MCP 工具在 http://127.0.0.1:8484/mcp 上提供（tools/list），此外还有场所内置的工具集：

工具	用途
surstor_store	存储一个制品（content、sessionId、agentId、modelVersion、usage）
surstor_retrieve	获取内容和完整的来源元数据
surstor_verify	检查 branch-ref、会话链（深度校验）、计划、签名
surstor_list	列出制品，可按会话筛选
surstor_diff	对比两个文本制品并生成统一差异
surstor_cost	汇总单个会话或所有本地会话的费用
surstor_sessions	列出会话及其链头、计数和总计
surstor_export	将会话导出为可移植、可离线验证的 JSON 包
surstor_prices_get	显示当前价格计划
surstor_prices_put	安装新的价格计划（仅影响未来费用）
surstor_search	本地语义搜索：针对自然语言查询返回排序后的制品 ID 和摘要
surstor_reindex	从 etch 存储重建搜索索引（清除后重放）

节点仅绑定到回环地址；匿名本地调用方拥有完整访问权限（auth.public.caps: unrestricted）。回环绑定可限制网络暴露，但其他本地进程仍能访问该节点。请仅使用可信客户端，并保持本地绑定。客户端配置请参阅 MCP 设置。

篡改证据

• 翻转内容单元中的一个字节 → branchRef 检查失败
• 改写中间事件 → 会话头（在捕获时记录）不会引用伪造内容；诚实链仍可通过验证
• 删除事件 → 深度验证／离线包验证会报告链缺口

操作演示请参阅 docs/tamper-demo.md。离线包（surstor_export）无需场所即可验证：surstor-node verify bundle.json 仅根据文件重新计算每个哈希和签名（退出代码为 0 表示有效）。

测试

mvn test

测试涵盖单元格／单元语义、JSON 往返哈希稳定性、基于引擎的篡改场景、预算执行、真实服务器重启后的持久化、版本化计费和资费边界、离线导出验证、嵌入确定性／相似度、Lucene 索引行为，以及基于引擎的语义搜索（存储→搜索→重新索引）。

本地语义搜索（v0.2.0-alpha.3）

surstor_search 按含义而非仅按 ID 对存储的制品排序——例如，查询“项目何时到期”会找到客户截止日期邮件。所有操作都在节点本地运行：内置的多语言 MiniLM 模型（ONNX，通过 DJL + ONNX Runtime）在 CPU 上嵌入文本，数据目录下的 Lucene HNSW 向量索引则负责查询。嵌入／搜索流程不会调用外部 API。 检索到的内容会返回给客户端：要让推理也保持在本地，主机还必须使用本地模型，且不能回退到云端或向外部转发。

只有字符串内容记录会被编入索引。请将简洁的记忆保存为 contentType: "text"，并使用字符串类型的 content；结构化的提示词／响应对象不会被编入语义索引。加密存储配置会禁用语义搜索；请改用会话列表，并按 ID 检索。

双单元格 CAD3 记录仍是唯一真实来源。嵌入和索引是衍生的、无签名的可丢弃数据：如果删除 search-index/，surstor_reindex 会从 etch 存储重建索引，不会丢失任何信息。索引失败不会导致存储失败。

配置（显示默认值）：

[search]
enabled = "true"
k_default = "10"

注意：适配器模块 jar 会增大约 190 MB（ONNX 原生二进制文件 + 内置模型）。此改动已接受用于 v0.2。

注意事项（v0.2.0-alpha.3）

• 当前价格表是带日期的估算快照，并非实时价格源。 原始的 8 月占位文件原样保留，用于历史核验；它已不再是默认文件。只有与旧版内置占位内容完全匹配时，才会自动升级。自定义价格表会予以保留。
• 预算限制按会话执行（适配器配置中的 session-budget-usd，默认值为 5.00）
• 在添加签名支持之前存储的制品无法通过 signature 检查。新安装请使用单独的全新数据目录；保留所需的任何现有记录。
• 没有匹配 API 资费的本地模型标识符仍属于未定价，而非零成本。SurStor 不估算电力或硬件成本。
• 此版本不提供自动记忆替换、面向用户的删除工作流或多用户隔离。节点间同步是可选的开发者预览功能；请参阅上方指南。