Nahuali

Nahuali

Agent 在信任记忆之前，可以先检查它。

_{从空白记忆到有证据支持的回忆：Nahuali 会展示哪些内容已可使用，并暂停仍需审核的内容。}

记忆检索通常从一个问题开始：哪些上下文看起来相关？ Nahuali 还会分别呈现另外四个问题：

• 哪条观察支持这段记忆？
• 有什么内容与它冲突，或会使它过时？
• 当前记录历史检查是否通过？
• 现有证据和健康检查是否支持使用此结果？

最终得到的是一款本地优先的记忆引擎，具备确定性的信任判定、防篡改的记录历史和可移植证据。其核心无需模型、账户、API 密钥、托管服务或 Docker。

60 秒快速体验

安装 macOS 或 Linux 二进制文件。安装程序需要匹配的 SHA-256 文件；以下固定路径还可以要求提供其 Sigstore 绑定包。

curl -fsSLo /tmp/nahuali-install.sh \
  https://raw.githubusercontent.com/Arakiss/nahuali/main/scripts/install.sh
sh /tmp/nahuali-install.sh
export PATH="$HOME/.nahuali/bin:$PATH"

在终端中运行 nahuali --version，即可看到真实的蜥蜴精灵图在构建标识旁动起来。当命令输出被捕获或重定向时，它会输出 Agent、安装检查和基准测试工具所需的稳定 nahuali <semver> 行。

记录一条观察，从中推导出一项主张（--source-last 会引用刚记录的事件），并在回忆时要求提供证据：

nahuali remember "Lena owns the release notes" --mention Lena --tag product
nahuali claim Lena owns "release notes" --source-last --confidence 0.92
nahuali recall "Who owns the release notes?" --authority --require-evidence
nahuali explore

nahuali explore 不只是一个记录浏览器。它会同时展示三个彼此独立的问题：

维度	解答的问题
MEMORY	这段记忆是否有足够支持，可以使用？
HISTORY	此存储的记录历史检查是否通过？
EXTERNAL	是否已将此状态与存储在此存储之外的授权参考进行比对？

按 / 搜索所有显示的记忆项字段，按 Tab 按记忆类型筛选，再按 j/k 检查结果背后的证据。蜥蜴会守护记忆，并随其状态变化。在 macOS 上使用 Ghostty 的真实窗口运行 scripts/render-readme-tui-gif.sh，即可重新生成上方的 GIF；不会用保真度较低的文本备用版本替换 README 的规范资源。

运行 nahuali demo，即可听取讲解，以非修改方式了解 Nahuali 如何检测特定的原位记录变更，并防止缺乏支持的记忆驱动行动。演示会说明哪些变更需要依赖外部保留的参考，而不能只依靠实时存储。

Nahuali 适用场景

当 Agent 需要本地或由操作员控制的记忆，并且使用结果的决策必须具备证据、健康信号和明确的完整性限制时，适合选择 Nahuali。它尤其适合作为重要记忆的可靠性层，而不是取代所有检索系统。

如果主要需求是托管运行、广泛的框架生态，或公开披露的 LoCoMo/LongMemEval 答案质量结果，请选择成熟的、以回忆为优先的平台或托管记忆平台。目前，Nahuali 不声称在这些方面领先。应用也可以将其他检索系统与 Nahuali 的证据和治理检查结合使用。

Nahuali 检查的内容

证据是记忆的一部分

观察是第一类事件。声明、关系、流程和意图都可以指向支持它们的事件。回忆可以拒绝缺少这条路径的结果，而不是用肯定的措辞来填补空白。

判定与相关性保持分离

考虑权威性的回忆会给出四种确定性判定之一：

判定	含义
certify	现有检查支持依据所附证据使用该内容。
advisory	可作为线索，但未经限定还不能作为事实重复。
warn	证据、时效性或存储健康问题需要核实。
block	在冲突解决之前，不得依据该记忆采取行动。

certify 判定既不能证明真实性，也不能证明作者身份。它表示现有证据和内容健康检查均已通过；请分别检查 HISTORY 和 EXTERNAL，以查看内部历史检查和可选的外部比对。Nahuali 将这些限制保留为机器可读信息，而不是隐藏在文档中。

历史可供检查

权威账本仅追加写入，并通过哈希链连接。Merkle 包含证明和一致性证明使验证更精简；Ed25519 检查点则依据外部操作员策略，将树大小、根哈希、链尖端、来源和账本沿袭绑定在一起。

Nahuali 不是区块链。它采用 RFC 9162 中标准化的透明日志原语，不会将私有记忆发布到公共网络，也不要求达成共识。独立见证方共同签名是未来计划，并非当前声称具备的能力。

单条声明可随附凭证传递

可移植的声明凭证仅包含所选声明、其证据事件、可选的来源信封、它们的 Merkle 包含路径，以及一个已签名的检查点。验证在线下进行，并且需要使用单独持有的策略：

CLAIM_ID="$(nahuali data --json | jq -r '.claims[-1].id')"
nahuali receipt-export \
  --claim-id "$CLAIM_ID" \
  --checkpoint checkpoint.json \
  --policy policy.json \
  --output claim-receipt.json

nahuali receipt-verify claim-receipt.json --policy policy.json

验证器会分别报告 receipt_integrity 和 content_authority。账本承诺绝不意味着所记述的陈述为真、其作者身份真实，或外部来源仍包含相同字节。

离线凭证验证只检查所选信封、其 Merkle 路径、溯源链接和检查点授权。它信任获授权的签名者对该根哈希的承诺；不会重放或验证完整的账本前缀。要进行更强的检查，请将账本与 checkpoint-verify 配合使用。凭证包含所选记忆的原文，应作为敏感数据处理，默认不应公开。

专为 Agent 打造，由人类操作

CLI 是权威接口。TUI、stdio MCP 服务、本地 HTTP API 和 Rust crate 都使用同一个确定性引擎：

接口	用途	参考
nahuali	可运行 Shell 的 Agent、脚本、持续摄取、检查、恢复、回执和 TUI	CLI
nahuali-mcp	提供 MCP 工具、但无法直接运行本地命令的宿主	MCP
nahuali-api	使用 OpenAPI 契约的本地 HTTP 集成	HTTP API
nahuali-core	在 Rust 中嵌入引擎	Core

对于基于终端的 Agent 工作负载，优先使用 CLI。它是直接、可编写脚本的 接口，支持批量命令，无需经过 MCP 工具调用往返，并且每次调用都会明确 指定确切的数据库和 JSON 契约。MCP 是为集成边界在于工具协议的客户端 提供的适配器。两个接口具有相同的信任语义；选择 CLI 并不会绕过验证。嵌入式 存储同一时间只能由一个进程持有：简短的 CLI 命令会排队等待（等待时间受 NAHUALI_STORE_LOCK_TIMEOUT_MS 限制，默认为 30 秒），但运行中的 MCP 服务、HTTP API 或 TUI 会在整个运行期间持有存储。需要由多个独立的长期运行 进程共享访问时，请使用远程 SurrealDB（--store ws://…）。

运行 nahuali init，即可在受支持的位置安装捆绑的 Agent 技能，并输出 原生 MCP 配置。Nahuali 也以 io.github.Arakiss/nahuali 的形式发布在官方 MCP Registry 中。原生和容器 配置请参阅 MCP 入门指南。

HTTP API 按设计不进行身份验证，不得暴露给不受信任的网络。

存储与恢复

SurrealDB 中的 memory_record 是事实来源。当前记忆视图、 图表、快照和语义向量都是派生数据，可重建。

• 普通写入会追加一条账本事件，更新内存视图，将期望的图与最近一次验证通过的图投影进行比较，并且只写入新增或已更改的行。不再存在的行会被移除。
• 如果无法信任已存储的投影检查点、架构版本、错误状态或内容清单，Nahuali 会清除派生图，并根据账本重建。恢复过程绝不会改写权威历史记录。
• 嵌入式 SurrealKV 是无需服务的默认选项。
• 远程 SurrealDB 支持有意共享的部署。
• 无需 Qdrant 或嵌入模型即可进行词法召回。
• Qdrant 和本地嵌入是可选的语义层。
• 图投影 v2 会隔离并发重建，并为每个由账本派生的投影表验证规范化内容清单，而不仅仅检查行数。当重建正在进行，或清单、架构版本或账本最新位置发生偏移时，依赖 SurrealDB 投影的实体、时间线、待处理工作和健康状态读取都会以失败关闭的方式拒绝读取。
• 语义验证器会在信任派生层之前检测向量索引偏移。
• 备份恢复会重放账本并重建派生状态。

嵌入式存储同一时间只能由一个进程持有。第二个进程会通过有界退避等待锁，因此并行执行的短命令会排队，而不是失败；如果超过 NAHUALI_STORE_LOCK_TIMEOUT_MS，进程会明确报错，而不会无限期等待或冒并发写入的风险。--store <PATH|URL> 用于选择存储位置；--database <NAME> 用于选择其中的数据库。

nahuali forget <id> --reason ... 会按 ID 擦除记忆，并保留可审计的记录： 记录该记忆（以及由它派生的记忆）的账本记录会变为经过编辑的存根，保留哈希链的可验证性；同时会生成 memory_forgotten 记录，说明请求者、请求时间和原因。此操作不会影响备份、导出、回执或尚未重建的语义索引。具体限制请参阅 GDPR 立场说明。

证据与评估限制

基于适配器的 Agent Memory Trust Benchmark 专为跨产品评估而设计，将来源追溯、拒绝回答、矛盾、过时、非变更式检查和篡改检测作为独立案例。仓库中保存的结果是 Nahuali 的一手证据，而非独立比较。 检索基准测试公开了经过版本固定的 24 条记忆、12 条查询语料中的每个排名项和延迟样本。

仓库中保存的 0.8.0-beta.9 结果是一手、版本匹配的源码构建结果。这些结果与二进制文件的 SHA-256 和源码修订版本绑定，但并不声称对应已发布的发行归档。新的已发布版本结果还必须与发布标签、目标平台、归档名称、归档摘要以及确切的二进制文件匹配，具体通过 scripts/verify-benchmark-artifact-identity.py 验证。

小型检索语料是回归门槛，不代表最先进水平，也不能替代 LoCoMo 或 LongMemEval。更全面的仓库内治理套件涵盖了信任相关的故障类别。运行受控 Beta 门槛：

bash scripts/verify-controlled-beta.sh

维护者可以单独验证所需的 GitHub 仓库设置：

NAHUALI_VERIFY_GITHUB_SETTINGS=1 bash scripts/security-supply-chain-check.sh

Beta 阶段限制

• 证据证明的是可追溯性，而非事实真实性。
• 可信检查点证明的是已提交的账本状态，而非独立时间。
• 要检测回滚或完全重新链接的历史记录，必须保留外部检查点和策略。
• 范围标签用于整理上下文；它们不是访问控制边界。
• 自检会提出待办工作，但绝不会自主改写记忆。
• forget 会从存储及其衍生层级中移除内容，但不会移除更早创建的副本；这并不能证明内容已被彻底清除。
• 不包含账户、托管同步、账单和托管控制平面。
• API 和存储行为在 1.0 之前仍可能发生变化。

使用不可替代的数据前，请阅读 BETA.md；在将判定结果视为授权边界前，请阅读完整的信任模型。

安装固定版本的发行版

上方的简易安装程序始终要求提供匹配的 SHA-256 资源文件。若要安装固定版本并同时要求 Sigstore bundle，请选择一个发行标签，并运行同一标签中的安装程序：

VERSION=vX.Y.Z-beta.N
curl -fsSLo /tmp/nahuali-install.sh \
  "https://raw.githubusercontent.com/Arakiss/nahuali/${VERSION}/scripts/install.sh"
NAHUALI_VERSION="$VERSION" NAHUALI_REQUIRE_SIGSTORE=1 \
  sh /tmp/nahuali-install.sh

此方式需要 cosign；如果无法验证归档校验和、签名身份或 bundle，则会停止。确切的身份、来源证明、SBOM 和手动验证方式，请参阅发行版验证。

更新通知

当有适用于你平台的更新版本时，nahuali briefing 和 nahuali session-resume 的人类可读输出会以一行通知结尾：

Update available: X.Y.Z-beta.N (you have X.Y.Z-beta.M) · https://github.com/Arakiss/nahuali/releases/tag/vX.Y.Z-beta.N

这是 Nahuali 自行发起的唯一网络请求。它会匿名调用一次 GET https://api.github.com/repos/Arakiss/nahuali/releases，最多每 24 小时一次，超时时间为 1.5 秒。它不会发送任何记忆内容、存储路径或标识符；按照 GitHub 的要求，User-Agent 标头仅包含 Nahuali 版本。检查结果（包括失败的尝试）会缓存在 $NAHUALI_HOME/update-check.json（默认路径为 ~/.nahuali）中。此通知不会出现在 --json 输出、其他命令、MCP 或 HTTP API 中；Nahuali 也绝不会自行安装任何内容。nahuali update-check 会立即检查并打印固定版本的安装命令。

设置 NAHUALI_NO_UPDATE_CHECK=1 可禁用所有更新检查，包括 update-check。如果设置了 CI，也会跳过自动检查。

从源码构建

cargo build --workspace
cargo test --workspace
cargo install --path crates/nahuali-cli --locked

仅在使用可选的远程开发技术栈和 Qdrant 时才需要 Docker。

深入了解

• 信任模型
• 已验证定律（Kani 证明和属性测试）
• 发布验证
• 自修复约定
• 治理基准测试
• 安全政策
• 贡献指南

问题和设计反馈请提交至 GitHub Discussions。Bug 报告和 基准测试贡献请使用结构化的 issue 模板。

许可证

Nahuali 采用 FSL-1.1-MIT 源代码可用许可证，即 Functional Source License 1.1 with an MIT future grant。你可以出于许可允许的目的查看、使用、复制、修改、可自托管并重新分发。不得将当前代码作为竞争性商业产品或服务提供；每个已发布版本会在两年后转为 MIT 许可证。 该许可证不妨碍他人独立重新实现本产品的理念。请阅读实用的许可常见问题；许可证文本仍是具有约束力的依据。