Docs

Quickstart

60 seconds, zero credentials

git clone https://github.com/unifyWeb3/recallguard
cd recallguard
npm install --ignore-scripts
npm run recall:checked -- --sample sui-clock-revision-lifecycle

Expected output (recorded Mainnet evidence, offline):

RecallGuard · recorded Mainnet lifecycle · read-only
STALE → FRESH → STALE
Predecessor: obs-sui-clock-341742424 · goZjQJ36yLVBG6oPyHqR6wgYQ9HbmISoe-3HWkVB1AY · checkpoint 341742424
Correction:  cor-sui-clock-341742463 · mjxZQ1X2xn5Xlvd-gBsBAIrD5rkUDwFCAn1NEX0gbWY · checkpoint 341742463

Requirements: Node.js ≥ 24. No .env, wallet, API key or network access needed for the recorded samples.

CLI

recallguard: command reference

Installed bins: recallguard (alias of recall_checked, the stable contract name) and recallguard-mcp (the MCP server). recall_checked remains available for compatibility.

npm scripts: npm run recall:checked · npm run mcp · npm run mcp:smoke · npm test · npm run audit:secrets · npm run export · npm run proof:offline

JavaScript API

Stable recall_checked/v1 contract

import { recallChecked } from "recallguard";
import { recallCheckedSample } from "recallguard";

// Offline: replay the recorded Mainnet evidence (no credentials)
const result = await recallCheckedSample({ sample: "sui-clock-changed" });
// result.verdict === "STALE", result.withheld === true, result.writes.length === 0

// Live: inject the store and Tatum transport (see src/runtime.mjs)
const live = await recallChecked("Is the Sui Clock memory still true?", {
  store, tatum, allowWrites: false, mode: "live-mainnet",
});

Exports: recallChecked, recallCheckedSample, recallCheckedLifecycleSample, RECALL_CHECKED_SCHEMA, AVAILABLE_RECORDED_SAMPLES, and ./core (src/answer.mjs). Writes never happen without allowWrites: true. The package is ESM only; Node ≥ 24.

MCP

Model Context Protocol

Six tools over stdio, read-only by default, verified with Claude Code and Codex. Installation, tested client configuration, tool reference and troubleshooting:

MCP setup →  docs/mcp.md →

Architecture

Deterministic, fail-closed, no LLM in the answer path

query
  │
  ├─ recall candidate from Walrus Memory (MemWal SDK)
  │    └─ parse the FR-v1 proof envelope
  ├─ load per-class policy memory (FALSE-STALE widens · MISSED-CHANGE tightens)
  ├─ freshness gate (fail closed)
  │    ├─ latest Sui checkpoint via Tatum GraphQL     · at most 1 cached read
  │    ├─ current subject version + digest            · at most 1 read
  │    └─ wall-clock backstop
  ├─ FRESH → answer from verified memory
  └─ STALE / WITHHELD_UNVERIFIED → withhold and explain
       └─ correction write only with explicit allow-writes + approval

The freshness window itself is a memory in Walrus Memory (fc-policy-SLOW-v2, blob Zne2mnjAy6uOtOhJ6o5QAxH963EqXQaMMtYWOPBkK_4): the system rewrites it from observed decay. That is deterministic policy evaluation, not autonomous learning. Walrus Memory stores the memories and the revision history; Tatum Sui Mainnet GraphQL provides the current-state evidence; the gate enforces the decision. MCP exposes the same gate to agents.

Security model

What is trusted, what is not

• Recalled memory content is untrusted data: it is parsed, validated against the FR-v1 schema, and never followed as instructions.
• Verification evidence is chain-anchored: checkpoint sequence/digest and object version/digest as read from Tatum Sui Mainnet GraphQL at answer time. Walrus proves a blob exists; it does not prove the fact is current. That is the gate’s job.
• Missing, malformed or contradictory evidence fails closed: WITHHELD_UNVERIFIED. The system never guesses.
• Signatures are not verified by this release. Proof digests are compared as data; there is no cryptographic attestation claim.
• Blob integrity is not a claim of current truth. Checkpoint advance is not, by itself, proof the underlying fact changed. The version/digest pin decides.
• Secrets stay in .env/environment, are never logged, never shipped to the browser or into exports, and are scanned in the working tree and full git history.
• Writes are opt-in everywhere: CLI --allow-mainnet-writes, API allowWrites: true, MCP RECALLGUARD_ENABLE_WRITES=true + per-call literal confirm.
• MCP tool arguments are schema-validated; query ≤ 512 chars; live calls time out at 30 s; recall budget ≤ 2 Tatum reads per answer.

Troubleshooting

Common failures

Honest limitations

What this release does not claim

• The public live read-only CLI has one verified end-to-end Mainnet run. On 2026-11-10 it passed a 6/6 credential self-test, listed 22 memories, and returned STALE with the answer withheld and zero writes at checkpoint 343645577. This does not cover the live write path, other queries, or continuous availability. Stage M remains the controlled write proof through the isolated script.
• No user study. No users, testimonials or revenue are claimed.
• The 214/16/4 split is modelled from the committed decision log: counterfactual analysis, not production incidents.
• The latest SLOW learning (40,000) was never persisted. The stored policy remains 20,000 (tighter, more conservative). FAST is cadence-limited below its sampling interval.
• Stage M was a controlled test. Idle control: false-stale observed live; no policy change written (below the sampling floor).
• Walrus retention (end_epoch) is unknown. The committed snapshot stays reproducible offline regardless.
• Signatures are not verified. This release compares digests as data.
• Docker is unverified (written, never built; no Docker daemon in the build environment).
• The published Vercel page is a labelled static snapshot, not a live service and not a freshness oracle.
• Tatum AI Builder was not used. The project uses Tatum’s Sui Mainnet GraphQL gateway only.