五周内发布十一次
在开发者版本发布后的前五周内，我发布了 11 个 Neotoma 版本。 CLI 现在可以在其他机器上运行，从而解锁登录。 MCP服务器足够稳定，适合日常代理使用。数据库可以承受操作员的错误。以下是变化的原因以及变化的原因。
要点
- CLI 从仅在作者的源代码检查中工作变为可以在任何计算机上通过全新的全局 npm 安装可靠地工作，这是最大的单一修复类别。
- MCP 稳定性改进，包括修复 stdio 流损坏和强化实体查询路径，使服务器可以安全地跨工具进行日常代理使用。
- 在生产数据丢失事件后发布的真正的数据库合并工具，具有冲突模式、空运行和从观察日志自动快照重新计算。
- 分页和实体过滤已修复，因此代理在分页结果时可以获得一致、正确的计数，从而消除了影响每个基于类型的查询的微妙错误。
- 下一阶段由评估者的反馈决定：简单的入门、与平台记忆的清晰共存故事，以及来源不可协商的领域的深度。
我在 2026 年 2 月 26 日至 4 月 1 日期间发布了 11 个 Neotoma 版本。最初的开发者版本 功能齐全，但很粗糙。它在我的机器上、在我的工作流程中运行，并融入了我的假设。五周的评估者反馈、每日测试和现实世界的使用情况浮出水面，而其他人却遇到了问题。
最大的改进是 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 条记忆的文章。这一经历促使我们在 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 安装的人来说，它们中的每一个都是一个问题。
下一阶段则不同。前五周的回答是“这对我以外的人有用吗？”下一个延伸回答“为什么有人会从他们已经构建的东西转向”。
我的评估小组 中至少有十个人正在构建自己的代理记忆。 Markdown 文件、SQLite、JSON 心跳、平面文件 CRM。同样的问题，不同的实现。他们中的一些人指出了他们的解决方案何时崩溃的确切触发器：来自多个代理的并发写入、他们无法回答的来源问题、规模超过了几十个活动实体。这些触发因素就是我的路线图。
具体的下一个目标来自评估者的要求，而不是来自功能愿望清单。
- 简单的入门，立即获得回报。 CLI 现在可以在其他机器上运行，但“有效”与“五分钟即可实现价值”不同。一位评估人员在设置虚拟机之前花了一个小时阅读文档。这需要五分钟，安装后发生的第一件事不应该是空数据库。代理驱动的入职培训应该扫描您的本地文件，用真实记录填充 Neotoma，并显示您以前没有的时间线或见解。顿悟时刻并不是“它已安装”。顿悟时刻是“它已经知道了关于我的数据的一些有用信息”。
- 一个清晰的共存故事。 多名评估者询问 Neotoma 是否应该与 Claude 的自动内存或 ChatGPT 的内置内存一起共存，或者替换它们。答案就在旁边，产品需要让这一点显而易见。
- **深入领域，出处是不可协商的。**医疗保健、合规性、财务审计：这些领域的评估人员表示，这些语言已经适合。这项工作是为这些垂直领域制定架构并提供具体保障。
更深层次的架构工作来自于我自己的日常使用，而不是评估者的要求。将 Neotoma 作为我的主要记忆层运行了几个月，但出现了外部人不会注意到的结构问题。
- 有界收敛。 代理是随机的。根据模型情绪，相同的用户消息可以产生不同的实体类型、字段名称和关系结构。我的实例有 170 种实体类型，其中一些是漂移的，而不是真正的本体。下一个版本添加了写入时规范化：别名映射，使“purchase”和“transaction”解析为相同的规范类型，模糊字段匹配，使“amount”和“amount_eur”不会分叉模式，以及检索增强存储，以便系统在代理创建重复项之前检查重复项。
- 模式治理。 现在任何代理都可以在第一家商店发明新的实体类型。这种自由在早期很有用，但会造成大规模的清理问题。计划的治理层会在存储偏离规范模式时添加别名注册、弃用生命周期和诊断警告。系统仍然允许写入，但会在响应中提供反馈，以便代理进行自我纠正。
- 渐进式执行。 如今的模式仅推断一次，并且从未收紧。下一步是置信度跟踪：对类型进行足够的观察后，模式会具体化，并且系统可以对丢失的公共字段、类型不匹配和损坏的关系模式发出警告。不封锁商店，只是揭露看起来不对的地方。严格模式成为高风险类型的选择，例如提取差异很重要的财务记录。
Neotoma 是 GitHub 上的开源。如果您尝试过开发人员版本并遇到一些问题，那么其中许多问题已在这些版本中得到解决。如果您还没有尝试过，最好的起点是要求您的代理评估 Neotoma 是否适合您的工作流程。代理会阅读该页面，检查您的设置，并在您安装任何东西之前诚实地告诉您它是否合适。