{ "markdown": "# Nahuali\n\n**Memory an agent can inspect before it trusts.**\n\n

\n \"Nahuali\n

\n\n

From an empty memory to evidence-backed recall: Nahuali shows what is ready to use and pauses what still needs review.

\n\n

\n \"Tests\"\n \"Latest\n \"Sigstore-signed\n \"FSL-1.1-MIT\n

\n\nMemory retrieval usually begins with *what context looks relevant?* Nahuali\nalso exposes four separate questions:\n\n- What observation supports this memory?\n- What conflicts with it or makes it stale?\n- Do the current recorded-history checks pass?\n- Do the available evidence and health checks support using this result?\n\nThe result is a local-first memory engine with deterministic trust verdicts,\ntamper-evident recorded history, and portable evidence. Its core does not need a\nmodel, account, API key, hosted service, or Docker.\n\n## A 60-second tour\n\nInstall the macOS or Linux binary. The installer requires the matching SHA-256\nasset; the pinned path below can additionally require its Sigstore bundle.\n\n```bash\ncurl -fsSLo /tmp/nahuali-install.sh \\\n https://raw.githubusercontent.com/Arakiss/nahuali/main/scripts/install.sh\nsh /tmp/nahuali-install.sh\nexport PATH=\"$HOME/.nahuali/bin:$PATH\"\n```\n\nRun `nahuali --version` in a terminal to see the real axolotl spritesheet come\nalive beside the build identity. When the command is captured or redirected, it\nemits the stable `nahuali ` line expected by agents, install checks, and\nbenchmark tooling.\n\nRecord an observation, derive a claim from it, and require evidence at recall:\n\n```bash\nnahuali remember \"Lena owns the release notes\" --mention Lena --tag product\nnahuali claim Lena owns \"release notes\" --source-last --confidence 0.92\nnahuali recall \"Who owns the release notes?\" --authority --require-evidence\nnahuali explore\n```\n\n`nahuali explore` is not just a record browser. It keeps three independent\nquestions visible:\n\n| Axis | What it answers |\n|---|---|\n| `MEMORY` | Is this memory supported enough to use? |\n| `HISTORY` | Do this store's recorded-history checks pass? |\n| `EXTERNAL` | Was this state compared with an authorized reference kept outside this store? |\n\nPress `/` to search every displayed memory-item field, `Tab` to filter by memory kind, and\n`j`/`k` to inspect the evidence behind a result. The axolotl watches over the\nmemory and changes with its status. Rebuild the GIF above from real Ghostty\nwindows on macOS with `scripts/render-readme-tui-gif.sh`; the canonical README\nasset is never replaced by the lower-fidelity text fallback.\n\nRun `nahuali demo` for a narrated, non-mutating explanation of how Nahuali\ndetects a specific in-place record change and keeps unsupported memory from\ndriving action. The demo states which changes require an externally retained\nreference rather than relying on the live store alone.\n\n## Where Nahuali fits\n\nChoose Nahuali when an agent needs local or operator-controlled memory and the\ndecision to use a result must carry evidence, health signals, and explicit\nintegrity limits. It is especially useful as a reliability layer around\nconsequential memory rather than as a replacement for every retrieval system.\n\nChoose an established recall-first or managed memory platform when the main\nrequirement is hosted operation, a broad framework ecosystem, or publicly\ndisclosed LoCoMo/LongMemEval answer-quality results. Nahuali does not claim\nleadership on those axes today. An application can also pair another retrieval\nsystem with Nahuali's evidence and governance checks.\n\n## What Nahuali checks\n\n### Evidence is part of memory\n\nObservations are first-class episodes. Claims, relationships, procedures, and\nintentions can point back to the episode that supports them. Recall can refuse\nresults without that path instead of filling the gap with confidence language.\n\n### Verdicts stay separate from relevance\n\nAuthority-aware recall carries one of four deterministic verdicts:\n\n| Verdict | Meaning |\n|---|---|\n| `certify` | Available checks support use with the attached evidence. |\n| `advisory` | Useful as a lead, but not ready to repeat as fact without qualification. |\n| `warn` | Evidence, freshness, or store-health problems require verification. |\n| `block` | The memory must not drive action until the conflict is resolved. |\n\nA `certify` verdict proves neither truth nor authorship. It means the available\nevidence and content-health checks passed; inspect `HISTORY` and `EXTERNAL`\nseparately for internal history checks and an optional external comparison.\nNahuali keeps those limits machine-readable instead of hiding them in\ndocumentation.\n\n### History is inspectable\n\nThe authoritative ledger is append-only and hash chained. Merkle inclusion and\nconsistency proofs make verification compact; Ed25519 checkpoints bind a tree\nsize, root, chain tip, origin, and ledger lineage to an external operator policy.\n\nNahuali is not a blockchain. It applies the transparency-log primitives\nstandardized in [RFC 9162](https://www.rfc-editor.org/rfc/rfc9162.html) without\npublishing private memory to a public network or requiring consensus. Independent\nwitness co-signing is a future step, not a capability claimed today.\n\n### One claim can travel with a receipt\n\nPortable claim receipts contain only the selected claim, its evidence episode,\nan optional source envelope, their Merkle inclusion paths, and one signed\ncheckpoint. Verification is offline and requires a policy held separately from\nthe receipt:\n\n```bash\nCLAIM_ID=\"$(nahuali data --json | jq -r '.claims[-1].id')\"\nnahuali receipt-export \\\n --claim-id \"$CLAIM_ID\" \\\n --checkpoint checkpoint.json \\\n --policy policy.json \\\n --output claim-receipt.json\n\nnahuali receipt-verify claim-receipt.json --policy policy.json\n```\n\nThe verifier reports `receipt_integrity` separately from `content_authority`.\nLedger commitment never becomes a claim that the remembered statement is true,\nthat its author is authentic, or that an external source still contains the\nsame bytes.\n\nOffline receipt verification checks only the selected envelopes, their Merkle\npaths, provenance links, and checkpoint authorization. It trusts the authorized\nsigners' commitment to that root; it does not replay or validate the complete\nledger prefix. Use `checkpoint-verify` with the ledger for that stronger check.\nReceipts contain the selected memory verbatim and should be handled as sensitive\ndata, not published by default.\n\n## Built for agents, operable by humans\n\nThe CLI is canonical. The TUI, stdio MCP server, local HTTP API, and Rust crate\nall use the same deterministic engine:\n\n| Interface | Use it for | Reference |\n|---|---|---|\n| `nahuali` | Shell-capable agents, scripts, sustained ingestion, inspection, recovery, receipts, and the TUI | [CLI](crates/nahuali-cli/README.md) |\n| `nahuali-mcp` | Hosts that expose MCP tools but cannot run local commands directly | [MCP](crates/nahuali-mcp/README.md) |\n| `nahuali-api` | Local HTTP integrations with an OpenAPI contract | [HTTP API](crates/nahuali-api/README.md) |\n| `nahuali-core` | Embedding the engine in Rust | [Core](crates/nahuali-core/README.md) |\n\nPrefer the CLI for terminal-based agent workloads. It is the direct, scriptable\ninterface, supports batch commands without an MCP tool-call round trip, and\nmakes the exact database and JSON contract explicit in every invocation. MCP is\nan adapter for clients whose integration boundary is a tool protocol. Both\ninterfaces have the same trust semantics; choosing the CLI does not bypass\nvalidation. An embedded database has one process owner, so do not point a\nrunning MCP server and CLI processes at the same embedded database\nsimultaneously. Use remote SurrealDB when independent processes need shared\naccess.\n\nRun `nahuali init` to install the bundled agent skill where supported and print\na native MCP configuration. Nahuali is also published as\n`io.github.Arakiss/nahuali` in the official MCP Registry. See\n[MCP onboarding](crates/nahuali-mcp/ONBOARDING.md) for native and container\nconfigurations.\n\nThe HTTP API is unauthenticated by design and must not be exposed to an\nuntrusted network.\n\n## Storage and recovery\n\n`memory_record` in SurrealDB is the source of truth. The current-memory view,\ngraph tables, snapshots, and semantic vectors are derived and rebuildable.\n\n- A normal write appends one ledger event, updates the in-memory view, compares\n the desired graph with the last verified graph projection, and writes only\n rows that are new or changed. Rows no longer present are removed.\n- If the stored projection checkpoint, schema version, error state, or content\n manifest cannot be trusted, Nahuali clears the derived graph and rebuilds it\n from the ledger. Recovery never rewrites authoritative history.\n- Embedded SurrealKV is the zero-service default.\n- Remote SurrealDB supports deliberately shared deployments.\n- Lexical recall works without Qdrant or an embedding model.\n- Qdrant and local embeddings are optional semantic tiers.\n- Graph projection v2 fences concurrent rebuilds and validates a canonical\n content manifest for every ledger-derived projected table, not only row\n counts. SurrealDB projection-backed entity, timeline, pending-work, and health\n reads fail closed while a rebuild is active or when the manifest, schema\n version, or ledger tip drifts.\n- Semantic validators detect vector-index drift before that derived tier is trusted.\n- Backup restore replays the ledger and rebuilds derived state.\n\nThe embedded store has one process owner. A second process fails clearly rather\nthan waiting indefinitely or risking concurrent writes.\n\n## Evidence and evaluation limits\n\nThe adapter-based\n[Agent Memory Trust Benchmark](benchmarks/agent-memory-trust/README.md) is\ndesigned for cross-product evaluation of\nprovenance, abstention, contradiction, staleness, non-mutating inspection, and\ntamper detection as separate cases. The checked-in result is first-party\nNahuali evidence, not an independent comparison. The\n[retrieval benchmark](benchmarks/agent-memory-retrieval/README.md) publishes\nevery ranked item and latency sample for a versioned 24-memory, 12-query corpus.\n\nThe checked-in 0.8.0-beta.9 results are **first-party, version-matched source\nbuilds**. They are bound to a binary SHA-256 and source revision, but they are\nnot claimed to be the published release archives. New published-release results\nmust additionally match the release tag, target, archive name, archive digest,\nand exact binary through `scripts/verify-benchmark-artifact-identity.py`.\n\nThe small retrieval corpus is a regression gate, not a state-of-the-art claim\nand not a substitute for LoCoMo or LongMemEval. The broader checked-in\n[governance suite](GOVERNANCE_BENCHMARKS.md) exercises trust-specific failure\nclasses. Run the controlled-beta gate with:\n\n```bash\nbash scripts/verify-controlled-beta.sh\n```\n\nMaintainers can verify the required GitHub repository settings separately:\n\n```bash\nNAHUALI_VERIFY_GITHUB_SETTINGS=1 bash scripts/security-supply-chain-check.sh\n```\n\n## Beta boundaries\n\n- Evidence proves traceability, not factual truth.\n- A trusted checkpoint proves a committed ledger state, not an independent time.\n- Detecting rollback or a fully re-chained history requires retaining an external checkpoint and policy.\n- Scope labels organize contexts; they are not access-control boundaries.\n- Self-inspection proposes work but never rewrites memory autonomously.\n- Accounts, hosted sync, billing, and a managed control plane are not included.\n- APIs and storage behavior may still change before 1.0.\n\nRead [BETA.md](BETA.md) before using irreplaceable data and the full\n[trust model](TRUST_MODEL.md) before treating a verdict as an authorization\nboundary.\n\n## Install a pinned release\n\nThe short installer above always requires the matching SHA-256 asset. For a\nversion-pinned install that also requires the Sigstore bundle, choose a release\ntag and run the installer from that same tag:\n\n```bash\nVERSION=vX.Y.Z-beta.N\ncurl -fsSLo /tmp/nahuali-install.sh \\\n \"https://raw.githubusercontent.com/Arakiss/nahuali/${VERSION}/scripts/install.sh\"\nNAHUALI_VERSION=\"$VERSION\" NAHUALI_REQUIRE_SIGSTORE=1 \\\n sh /tmp/nahuali-install.sh\n```\n\nThis path requires `cosign` and stops if the archive checksum, signing identity,\nor bundle cannot be verified. See [release verification](RELEASE_VERIFICATION.md)\nfor the exact identity, provenance, SBOM, and manual verification path.\n\n## Build from source\n\n```bash\ncargo build --workspace\ncargo test --workspace\ncargo install --path crates/nahuali-cli --locked\n```\n\nDocker is needed only for the optional remote development stack and Qdrant.\n\n## Go deeper\n\n- [Trust model](TRUST_MODEL.md)\n- [Release verification](RELEASE_VERIFICATION.md)\n- [Self-repair contract](SELF_REPAIR.md)\n- [Governance benchmarks](GOVERNANCE_BENCHMARKS.md)\n- [Security policy](SECURITY.md)\n- [Contributing](CONTRIBUTING.md)\n\nQuestions and design feedback belong in\n[GitHub Discussions](https://github.com/Arakiss/nahuali/discussions). Bugs and\nbenchmark contributions have structured\n[issue templates](https://github.com/Arakiss/nahuali/issues/new/choose).\n\n## License\n\nNahuali is source-available under FSL-1.1-MIT, the\n[Functional Source License 1.1 with an MIT future grant](LICENSE). You may\ninspect, use, copy, modify, self-host, and redistribute it for permitted\npurposes. Offering the current code as a competing commercial product or\nservice is restricted; each published version converts to MIT after two years.\nThe license does not prevent an independent reimplementation of the product's\nideas. Read the practical [licensing FAQ](compliance/licensing-faq.md); the\nlicense text remains the binding source.\n", "bytes": 14385, "sha": "1df5b033f438da13e5e8601a775ed673fc3bd6ce188c689d6bf1035277df057d", "repo_slug": "arakiss/nahuali", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_arakiss_nahuali_1e889bdb/readme" }