Nahuali

The trust layer for agent memory. Nahuali shows what a memory is based on, whether it is safe to use, and when an agent should refuse it.

Most memory systems optimize for finding relevant context. Nahuali asks the question that comes next: should the agent trust what it found?

It records observations, claims, relationships, procedures, and intentions in an append-only ledger. Recall can return the supporting evidence and a deterministic trust verdict. Self-inspection finds unsupported, stale, or contradictory memory without silently rewriting it. The default ledger is hash chained, and an operator can sign its tip to detect a fully rewritten history.

Nahuali is local-first, source-available, and in public beta.

_{nahuali explore: inspect what the agent remembers, why it trusts it, and whether the ledger is intact. The nahual in the bottom-right corner mirrors the current trust verdict and moves without obscuring the cockpit.}

Quickstart

Install the signed macOS or Linux binaries:

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

Record an observation, derive a claim from it, and inspect the result:

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 --json
nahuali self-inspect --json

This is real persistent memory. The default store lives under ~/.nahuali/data, survives process restarts, and needs no Docker, database server, model, account, or API key. Set NAHUALI_DB_URL when you want a shared remote SurrealDB deployment instead.

After upgrading Nahuali, restart any application that keeps nahuali-mcp running. This ensures the CLI and the long-lived MCP server open the embedded store with the same engine version.

For a narrated integrity example with no writes, run:

nahuali demo

That command explains the hash chain and signed checkpoint without changing your store. The end-to-end demo below is a separate, reproducible product flow. From a source checkout, run scripts/run-launch-demo.sh verify. It creates a disposable store, follows it through the CLI, TUI, and a real MCP tool call, then asserts the expected results.

An evidence-backed claim can drive action. A competing unsourced claim is retained but blocks action, and self-inspection explains the contradiction without silently rewriting the ledger.

Why this is different

Memory failure	Nahuali response
A relevant claim has no source	Return it as unsafe, not as a trusted fact
Good and weak memories are mixed together	Give each result its own evidence and verdict
Claims conflict or become stale	Surface the affected records for explicit review
A model proposes a repair	Validate the evidence and append an audited repair event
A historical record is edited	Break the ledger chain at the next record
The history is rewritten and re-chained	Refuse the old operator-signed checkpoint

The four trust modes are deterministic:

• certify: the available checks support using the result.
• advisory: useful as a lead, but not safe to state without qualification.
• warn: evidence or health problems require verification.
• block: the result must not drive action until the conflict is resolved.

A verdict does not prove that remembered content is true. It makes the reason for trust inspectable: evidence, provenance, confidence, freshness, contradictions, and ledger integrity. The exact guarantees and limits live in the trust model.

Use it from an agent

Nahuali ships a stdio MCP server with tools for capture, recall, inspection, review, repair, intentions, backup, and ledger verification.

Run nahuali init to install the bundled skill where supported and print a native-binary MCP configuration. The server is also published as io.github.Arakiss/nahuali in the official MCP Registry and as an OCI image:

{
  "mcpServers": {
    "nahuali": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "nahuali-data:/data",
        "ghcr.io/arakiss/nahuali-mcp:latest"
      ]
    }
  }
}

The named volume keeps memory across container restarts. See MCP onboarding for native and container configurations.

The trust loop

flowchart LR
    A[Observed episode] -->|evidence| B[Claim or link]
    B --> C[Authority-aware recall]
    C --> D{Trust verdict}
    D -->|certify| E[Use with evidence]
    D -->|advisory, warn, block| F[Inspect and review]
    F --> G[Explicit repair or resolution]
    G --> H[Append-only audit event]
    H --> C

The deterministic core never calls an LLM. A model may propose a repair, but the engine classifies, gates, and records it. Contradictions are never silently overwritten.

Interfaces

Interface	Purpose	Reference
nahuali	Local workflow for agents, operators, audits, backup, and migration	CLI
nahuali-mcp	Structured tools and resources for MCP clients	MCP
nahuali-api	Local HTTP integrations with an OpenAPI contract	HTTP API
nahuali-core	Deterministic Rust engine and public data contracts	Core

The local HTTP API is unauthenticated. Do not expose it to an untrusted network. Nahuali does not currently provide accounts, hosted sync, billing, or a managed control plane.

Storage

SurrealDB's memory_record table is the source of truth. Current memory, graph tables, snapshots, and semantic vectors are derived and rebuildable.

• Embedded SurrealKV is the zero-service default.
• A remote SurrealDB endpoint supports shared deployments.
• Qdrant is optional and used only for semantic recall.
• Deterministic lexical recall works without Qdrant or a model.
• reconcile verifies the ledger and rebuilds derived data.
• Backup and restore operate on the authoritative record ledger.

The embedded store has one process owner. A long-running MCP or HTTP server owns the local store while it is active; a second process fails clearly instead of waiting or risking concurrent writes. Use remote SurrealDB when several independent processes need the same memory.

Reproducible evidence

The governance benchmark suite tests provenance coverage, contradiction and staleness detection, trust-verdict calibration, ledger tampering, and attestation recovery against checked-in fixtures.

The vendor-neutral Agent Memory Trust Benchmark defines an adapter contract for comparing these capabilities across memory systems. It reports each capability separately and keeps failures and unsupported controls visible.

Run Nahuali's release gate:

bash scripts/verify-governance-benchmarks.sh
bash scripts/verify-controlled-beta.sh
NAHUALI_VERIFY_GITHUB_SETTINGS=1 bash scripts/security-supply-chain-check.sh

Beta limits

• APIs and storage behavior may still change before 1.0.
• Self-inspection proposes work but never writes automatically.
• Evidence proves traceability, not factual truth.
• The operator must retain a trusted signed checkpoint to detect rollback or a fully re-chained history.
• Scope labels separate memory contexts but are not access-control boundaries.
• Semantic recall requires an optional Qdrant service; the default lexical path does not.

Read BETA.md before using irreplaceable data.

Build from source

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

Docker is only needed for the optional remote development stack and Qdrant:

docker compose up -d

More documentation

• Trust model
• Release verification
• Self-repair contract
• Governance benchmarks
• Security policy
• Contributing

Questions, use cases, and design feedback belong in GitHub Discussions. Bugs and benchmark contributions have structured issue templates.

License

Nahuali uses the Functional Source License 1.1 with an MIT future grant. Each release converts to MIT two years after its release date.