我在 2026 年 2 月 26 日至 4 月 1 日期间发布了 11 个 Neotoma 版本。最初的[开发者版本](/posts/neotoma-developer-release) 功能齐全，但很粗糙。它在我的机器上、在我的工作流程中运行，并融入了我的假设。五周的评估者反馈、每日测试和现实世界的使用情况浮出水面，而其他人却遇到了问题。

最大的改进是 CLI 可靠性，因为 CLI 是新用户接触的第一个东西，也是在入门过程中第一个可能失败的东西。

第二个是 MCP 稳定性，因为 MCP 服务器是代理每天调用数百次的地方，那里的静默故障会在没有警告的情况下破坏工作流程。

第三是真实条件下的数据完整性。这篇文章介绍了 npm 包中的更改，而不是网站或文档中的更改。

节奏是每三到四天发布一次。某些版本修复了单个分页错误。其他人则将 CLI、HTTP 操作和 MCP 运行时进行了数周的强化。共同点是，每个版本都解决了一些让第一次尝试使用 Neotoma 的人感到困惑或困惑的问题。

## CLI 不再假设是我干的

开发人员发布的 CLI 在我的机器上通过源代码检查工作。这是我测试过的唯一上下文。第一波反馈明确表明这还不够。

第一个修复是路径解析。当您通过 npm 全局安装 Neotoma 并从任意目录运行它时，CLI 需要在没有源签出的情况下找到自己的资源。 v0.3.3 添加了已安装包位置的后备解决方案。 v0.3.8 在 npm tarball 中附带了 `openapi.yaml`，因此规范文件始终可用，而不仅仅是在克隆存储库时可用。

接下来是环境检测。 CLI 现在区分从源签出运行和从全局 npm 安装运行。需要源的功能（如隧道模式）通过清晰的错误消息而不是神秘的故障进行门控。 CLI 输出中的术语也发生了变化：“Neotoma 路径”表示配置的运行时位置，“源签出”表示开发工作流程。以前的语言对两者都使用“repo”，这让通过 npm 安装且没有 repo 的人感到困惑。

初始化流程在多个版本中得到了改进。 v0.3.6 到 v0.3.9 逐步加强了首次运行体验：更好的环境定位、更清晰的启动 UX、更强的配置路径处理。到 v0.3.10，CLI 可以检测自己的安装上下文并调整行为，而无需用户告诉它任何内容。

v0.3.11 是最大的单一 CLI 版本。它添加了灵活的搜索（带有位置标识符的“neotoma实体搜索”、“--identifier”和“--query”作为别名）、存储的首选结构化输入路径（“--entities”和“--file”以及现有的“--json=”）以及用于将 SQLite 数据库与冲突解决模式相结合的“storage merge-db”。 v0.4.0 使跨节点、bun 和 deno 包装器的参数处理更加可靠。

最终效果：CLI 从“在我的机器上运行”变为“在其他人机器上的任意目录中的全新 npm 安装上运行”。这个差距比我预想的要大。

## MCP 日常使用变得安全

MCP 服务器是代理与 Neotoma 交互的方式。它需要以不同于 CLI 的方式可靠。代理不会读取错误消息。他们重试、误解或默默地放弃上下文。

第一个 MCP 修复虽然微不足道，但很重要。 v0.3.8 移动模式注册表信息注销标准输出。 MCP 使用 stdio 在代理和服务器之间进行结构化通信。记录到同一流会破坏协议。代理会收到乱码响应或挂起。将日志移至 stderr 修复了一类难以诊断的静默故障。

v0.3.11 包括更广泛的 MCP 运行时更新以及 HTTP 操作层和实体查询处理。与标识符式查询相比，列表式查询的检索路径变得更加可靠。词汇搜索集成得到了回归覆盖。 MCP 服务器和 HTTP API 现在共享更多行为，因此代理和直接 API 使用者会看到一致的结果。

v0.4.0 继续这项工作，改进了时间线生成、观察投影、快照计算和模式注册表行为。这些是确定代理在查询实体状态时看到的内容的内部机制。让他们正确意味着座席在整个会话中获得一致、正确的答案。

## 分页和实体过滤变得诚实

v0.3.4 修复了暴露出更广泛问题的特定错误。当您按类型（例如所有任务）查询实体时，已删除的实体包含在结果计数中，但从可见结果中过滤掉。分页偏移量使用未过滤的计数。结果是：页面中的项目少于预期、总数不一致，以及代理认为他们已检索到所有内容，但实际上并没有。

解决方法是在过滤之后而不是之前进行分页。现在总数反映了可见实体。这听起来微不足道，但对于任何分页结果的代理工作流程都很重要，一旦您拥有超过几十个任何类型的实体，这就是大多数结果。

## 数据库合并成为一个真正的工具

我在三月份[写了一篇关于丢失和恢复 6,000 条记忆的文章](/posts/how-i-lost-and-recovered-6000-memories)。这一经历促使我们在 v0.3.11 中将“storage merge-db”作为正确的 CLI 命令提供。

该命令通过显式冲突处理合并两个 SQLite 数据库。三种模式：“safe”（默认，任何冲突都会失败）、“keep-target”（目标在冲突时获胜）、“keep-source”（源获胜）。试运行模式会在提交之前预览将插入的内容以及会发生冲突的内容。合并后，该命令从观察日志中重新计算实体快照，以便派生状态保持正确。

这不仅仅是一个恢复工具。它处理来自多个 Neotoma 实例的数据组合、机器之间的迁移以及合并开发和生产数据库。基于观察的架构使所有这些操作都是安全的，因为观察是不可变的，并且在给定相同观察集的情况下实体状态是确定性的。

## 扩展了多工具支持

开发人员版本通过 MCP 支持 Cursor、Claude 和 ChatGPT。 v0.3.11 添加了明确的 ChatGPT 集成文档并发布了“openapi_actions.yaml”，这是一个用于自定义 GPT 和 HTTP 操作工作流程的 OpenAPI 形状的表面。这意味着 ChatGPT 不仅可以通过 MCP，还可以通过自定义 GPT 使用的本机操作界面来使用 Neotoma。

OpenAPI 合约本身在 v0.3.11 和 v0.4.0 之间进行了更新，以反映操作层的变化。如果您通过 API 以编程方式使用 Neotoma，这些版本需要重新检查任何生成的客户端。

## 旧的提取路径已删除

v0.4.0 删除了 `llm_extraction` 代码路径。这是一种在存储管道中使用语言模型的传统方法。 Neotoma 的设计原则是，没有任何 LLM 位于存储或检索的关键路径上。提取发生在代理层，而不是 Neotoma 内部。删除旧路径使代码库与该原则保持一致并简化了内部结构。

这种变化对用户来说是不可见的，但对项目的方向很重要。 Neotoma 是真相层，而不是推理层。撤离路径模糊了这条界限。现在却没有了。

## 节奏教会了我什么

五周内发布十一个版本并没有计划。每个版本都会响应特定的内容：错误报告、令人困惑的首次运行体验、生产中中断的工作流程、我无法忽视的架构不一致。

出现的模式是：日常使用会出现问题，评估者反馈确认优先级，小版本在问题复合之前修复它们。另一种选择是将更改批量发布到大型版本中，这将使真正的用户在数周内陷入不良行为。

开发者版本被定位为“故意粗糙”。那是诚实的。我低估了有多少粗糙的边缘是特定于我自己的设置的。路径解析、环境检测、stdio 安全、分页一致性：这些对我来说都不是问题，因为我在终端中使用数据从源运行。对于第一次通过 npm 安装的人来说，它们中的每一个都是一个问题。

下一阶段则不同。前五周的回答是“这对我以外的人有用吗？”下一个延伸回答“为什么有人会从他们已经构建的东西转向”。

我的[评估小组](/posts/customer-research-through-agents) 中至少有十个人正在构建自己的代理记忆。 Markdown 文件、SQLite、JSON 心跳、平面文件 CRM。同样的问题，不同的实现。他们中的一些人指出了他们的解决方案何时崩溃的确切触发器：来自多个代理的并发写入、他们无法回答的来源问题、规模超过了几十个活动实体。这些触发因素就是我的路线图。

具体的下一个目标来自评估者的要求，而不是来自功能愿望清单。

- **简单的入门，立即获得回报。** CLI 现在可以在其他机器上运行，但“有效”与“五分钟即可实现价值”不同。一位评估人员在设置虚拟机之前花了一个小时阅读文档。这需要五分钟，安装后发生的第一件事不应该是空数据库。代理驱动的入职培训应该扫描您的本地文件，用真实记录填充 Neotoma，并显示您以前没有的时间线或见解。顿悟时刻并不是“它已安装”。顿悟时刻是“它已经知道了关于我的数据的一些有用信息”。
- **一个清晰的共存故事。** 多名评估者询问 Neotoma 是否应该与 Claude 的自动内存或 ChatGPT 的内置内存一起共存，或者替换它们。答案就在旁边，产品需要让这一点显而易见。
- **深入领域，出处是不可协商的。**医疗保健、合规性、财务审计：这些领域的评估人员表示，这些语言已经适合。这项工作是为这些垂直领域制定架构并提供具体保障。

更深层次的架构工作来自于我自己的日常使用，而不是评估者的要求。将 Neotoma 作为我的主要记忆层运行了几个月，但出现了外部人不会注意到的结构问题。

- **有界收敛。** 代理是随机的。根据模型情绪，相同的用户消息可以产生不同的实体类型、字段名称和关系结构。我的实例有 170 种实体类型，其中一些是漂移的，而不是真正的本体。下一个版本添加了写入时规范化：别名映射，使“purchase”和“transaction”解析为相同的规范类型，模糊字段匹配，使“amount”和“amount_eur”不会分叉模式，以及检索增强存储，以便系统在代理创建重复项之前检查重复项。
- **模式治理。** 现在任何代理都可以在第一家商店发明新的实体类型。这种自由在早期很有用，但会造成大规模的清理问题。计划的治理层会在存储偏离规范模式时添加别名注册、弃用生命周期和诊断警告。系统仍然允许写入，但会在响应中提供反馈，以便代理进行自我纠正。
- **渐进式执行。** 如今的模式仅推断一次，并且从未收紧。下一步是置信度跟踪：对类型进行足够的观察后，模式会具体化，并且系统可以对丢失的公共字段、类型不匹配和损坏的关系模式发出警告。不封锁商店，只是揭露看起来不对的地方。严格模式成为高风险类型的选择，例如提取差异很重要的财务记录。

Neotoma 是 [GitHub 上的开源](https://github.com/markmhendrickson/neotoma)。如果您尝试过开发人员版本并遇到一些问题，那么其中许多问题已在这些版本中得到解决。如果您还没有尝试过，最好的起点是[要求您的代理评估 Neotoma 是否适合您的工作流程](https://neotoma.io/evaluate)。代理会阅读该页面，检查您的设置，并在您安装任何东西之前诚实地告诉您它是否合适。