Neotoma 是面向 AI 智能体的状态层，定位为人类与智能体系统的共享、受治理记录系统。它要解决的核心问题是：智能体产出的值无法说明自己的版本、来源或是否仍然有效。Neotoma 对每个事实进行版本化、归属到来源并可重放，以此回答“什么是真实的”。
用途 Neotoma 不是聊天记忆或向量缓存，而是确定性的状态层。它从来源摄取原始输入，存储为不可变观察，再将观察归约成实体当前快照。任何内容都不会被覆盖：纠正或重新解释只会追加新观察，历史保持完整且可重放。其长期目标是集体认知一致性——不是“更好的语义记忆”，而是人类与智能体共同维护的、确定、受治理的多方状态，具备归属、可纠正、可处理分歧、可移植且不依赖任何单一模型或应用。它与 Ateles 互补：Neotoma 回答“什么是真实的”（真相、记忆、溯源），Ateles 回答“谁被授权”（发起、委派、批准）。
主要能力 三个属性贯穿所有接口：确定性——实体 ID、观察 ID、事件 ID 和归约输出均由输入经哈希派生，相同观察无论顺序或时间都产生相同快照，数据路径中不引入随机数或挂钟值；不可变与可审计——来源和观察均为追加式，快照中每个字段都可追溯到设置它的观察，再追溯到来源、解释、智能体和时间戳；自托管与可移植——引擎是嵌入式 SQLite 加内容寻址文件存储，位于用户控制的目录下，可选 AES-256-GCM 静态加密，数据不用于训练，可完整导出，单用户模式下数据完全本地。 处理流程为：来源（原始输入以 SHA-256 内容哈希去重存储一次，有确定性来源 ID）→ 解释（从来源提取结构化字段，可为 LLM 解释运行并记录模型、温度和提示）→ 观察（每个提取事实成为带哈希 ID 的不可变观察）→ 实体解析（按类型模式驱动的确定性规范名称映射到实体，必要时创建）→ 快照（按字段合并策略归约所有观察，顺序为 observed_at DESC, id ASC，并生成字段到观察的溯源映射）→ 时间线与关系（日期字段生成确定性时间线事件，类型化关系连接实体成图）。 能力面包括约 60 个 MCP 工具和约 100 个 REST 端点，均基于同一组操作。具体包括：摄取与存储结构化记录或原始文件（文件摄取可从 PDF、CSV、Parquet、JSON 和纯文本提取文本，图片和音频作为原始来源存储，写入通过 idempotency_key 幂等）；按标识符查找实体、多信号身份解析与置信度评分、列出观察、检索字段溯源链、遍历关系图 N 跳、拉取完整图邻域，配置嵌入键后可在本地 sqlite-vec 上对实体快照做语义向量搜索；提交纠正（作为高优先级观察，在快照中始终获胜，而非编辑）；模式从数据推断、从重复未知字段推荐、可自动增强或增量更新并版本化，新实体类型无需改代码；创建类型化关系（如 PART_OF、DEPENDS_ON、REFERS_TO、DUPLICATE_OF），跨类型和日期范围查询时间线事件；管理实体生命周期，包括合并重复、按谓词拆分、软删除与恢复、列出潜在重复、面向 GDPR 的删除，合并和拆分是事务性且有审计；控制多智能体访问，每次写入归属到智能体身份（验证的密钥指纹、JWT 主体或客户端名称），智能体授权表达最小权限能力；联邦、同步与摄取，包括注册对等实例并同步实体（可配置范围和冲突解决：最后写入胜出、来源优先或手动），通过 webhook（HMAC 签名）或 Server-Sent Events 订阅变更，接受访客实体提交，把 GitHub issue 镜像为会话线程，把数据镜像为确定性、可 git 跟踪的规范 Markdown；导出数据，包括有界 MEMORY.md 摘要、带完整溯源和归属元数据的 JSON 快照导出，或每个实体、关系、来源和时间线日的完整 Markdown 镜像。
使用方式 同一状态和保证有四种访问途径，均映射到一个 OpenAPI 支撑的契约：MCP 服务器、REST API、CLI 和内置 Web Inspector。Inspector 是打包进构建的单页 Web 应用，由 API 服务器提供（浏览器访问 /，无需单独部署），作为数据存储的操作台，包含实体浏览/详情/字段纠正/历史与溯源/实体时间线、观察/来源/解释/近期活动、交互式知识图谱浏览器、关系与全局时间线、模式与实体类型、智能体与授权、对等方与订阅、issue 与会话轮次（智能体审计轨迹）、访问策略与合规、搜索/分析/用量、设置（含深色模式）、沙盒界面及 /docs 应用内文档浏览器。 前置条件：Node.js 20.x（见 .nvmrc）和 npm 9+，本地存储无需 .env。neotoma doctor 命令检查环境、数据库和安全配置。CLI 还处理 MCP 配置扫描与同步、harness 配置、生命周期钩子安装、对等方与访问管理、计划、转录与入职导入、服务器与数据库管理、记忆导出和规范镜像。智能体通过 MCP 工具调用执行相同操作，如 store、retrieve_entities、retrieve_entity_by_identifier，每次 MCP 调用都会记录其等价 CLI 调用。安装方式当前为 npm 和 CLI，引导式安装尚不可用。 客户端 SDK：@neotoma/client（TypeScript）和 neotoma-client（Python）。针对各 harness 的包位于 packages/ 下：claude-code-plugin、cursor-hooks、opencode-plugin、codex-hooks、claude-agent-sdk-adapter。Neotoma 还作为原生 OpenClaw 插件发布，kind 为 "memory"，可填充专用记忆槽并将所有 MCP 工具注册为智能体工具。技能（Skills）是引导式工作流，教智能体导入、提取和持久化数据，随 npm 包发布并由 neotoma setup 安装；普通存储和检索无需技能，会话开始时提供的实时 MCP 工具说明直接覆盖 store/query/recall。
存储、隐私与安全 存储为本地 SQLite（better-sqlite3，WAL 模式）加内容寻址文件存储，位于 NEOTOMA_DATA_DIR 下，区分 dev 和 prod 配置，语义搜索在本地使用 sqlite-vec。数据不用于训练，日志和事件负载携带 ID 而非 PII。单用户模式下数据完全本地；一旦启用 MCP OAuth、对等同步或托管多用户实例，数据按相应配置共享。可选 AES-256-GCM 列加密敏感内容和元数据，密钥来自密钥文件或 BIP-39 助记词；部分表（如事件日志）尚未列加密，需搭配加密卷实现全面覆盖。认证包括单用户本地认证、托管使用的 MCP OAuth、智能体可选硬件证明及明确的逐操作访问控制。
适用场景与限制 Neotoma 主要面向构建和运维 AI 智能体的开发者，这些开发者需要跨工具共享的持久、确定性、可审计记忆层。产品以 MCP 服务器和 REST API 交付，带开箱即用钩子包（Claude Code、Cursor、Codex、OpenCode）、Claude Agent SDK 适配器及 TypeScript 和 Python 客户端，核心价值是智能体循环的记忆引擎基础设施，而非终端用户应用。另外两类用户也随之而来：在单用户安装上运行个人跨助手记忆的个人，以及运行共享多用户实例并带智能体访问控制的运营者。智能体身份和授权机制是支持所有用户溯源与归属的基础设施。 它不面向休闲笔记、PKM/Obsidian 风格的人工驱动知识库，或需要完全托管、本机无需运行任何东西的用户——Neotoma 设计上本地优先，且这一点不是临时状态。Neotoma 处于开发者预览阶段，已在真实智能体工作流中日常使用。版本 v0.17.0，许可证 MIT，存储为本地（SQLite + 本地文件）。
