mneme-ai

README

The Trust & Cost Layer for AI Agents

_{μνήμη · NEE-meh · Greek for "memory." A local-first boundary every AI agent crosses: it verifies before it acts, keeps your code & secrets from leaking to the model (with a signed, offline-auditable proof), remembers across sessions & vendors, and meters the tokens it saves you.
Vendor-neutral · MIT · air-gap-ready.}

_{New here? → 60-second start (one line for your case) · or run mneme quickstart. Don't read the 988-tool list.}

_{🛰 The Matrix Rail — one local-first, signed, streaming pipe every AI agent crosses, reachable three ways (MCP · gRPC · CLI) over a single core. The honest "Visa of AI context": authorize → screen → clear, with a tamper-evident receipt, your code never leaving the box. architecture →}

---

🎖 The Agent Run Certificate — proof a giant can't issue for itself

A portable, signed certificate of an agent's whole run (audit trail + every human approval) that anyone verifies offline, whose summary re-derives from the evidence — so it can't lie about its own run. Vendor-neutral, local-first. mneme agentcert build. _{over HTTP, any vendor + underwrite a run →  ·  govern an agent in 5 lines →  ·  prove where it ran →}

💗 THYMOS — the first AI memory with a heart you can audit

A signed, measurable affective core (salience · valence · bond) that decays like a mind, an attractor that ranks inbound by resonance — and, uniquely, can prove it forgot (an offline attestation for GDPR Art. 17). Not sentience — a heart you can measure. thymosGauntlet=100 · mneme thymos. _{the affective core + Proof-of-Forgetting →  ·  see it live →}

🛰 APHELION — the agent brain that goes farther than the cloud

The first governance that doesn't assume a cloud: an agent (Mars · severed link · air-gapped) governs itself against a local charter and hands back one signed capsule proving charter-compliance for the whole offline window (a violation can't be hidden) — verified offline by any vendor, bundled into a user-owned Accountability Dossier. aphelionGauntlet=100 · mneme aphelion. _{the brain beyond the cloud + the Accountability Dossier →}

🩻 Try it live

Paste any public repo and get a signed, reproducible health X-Ray in seconds — no install. xray.mneme-ai.space  ·  _{how it works + self-host →}

📟 Cosmic Pager

Your AI works while you sleep. You approve it from your phone.

Close the lid and walk away. Your AI agent keeps working — and the instant it needs a yes / no / a typed answer, it pings your Telegram in real time. Tap ✅ / ⛔ (or type a reply) from anywhere on earth, and the agent picks up your answer and keeps going — for real. No more babysitting a terminal.

⚠️ One hard requirement (all OS): the laptop must stay AWAKE with the lid closed — NOT asleep. A truly sleeping CPU is halted, so the agent pauses until it wakes (physics, not a bug). autosetup sets lid-close → "do nothing" for you. Windows / Linux: works on battery. macOS: the firmware sleeps on lid-close on battery regardless — keep it on AC power (or an external display) for clamshell stay-awake.

How it's different from a hosted "remote control": there is no server, no public IP, no cloud session to keep alive. The brain stays on your machine — only a one-line summary + hash ever leaves it (never your code), and every approval is a signed, court-admissible transfer of authority.

Setup is two steps — your AI does the rest:

1. In Telegram, message @BotFather → /newbot → copy the token.
2. Tell your AI: "set up phone approvals, here's my token: …" — it runs mneme pager autosetup, which finds your chat-id, wires the hook, sets lid-stay-awake, and starts paging automatically. You never type a Mneme command.

_{Full 60-second bot guide + spec → docs/COSMIC-PAGER.md}

Add LINE · Discord · WhatsApp · Slack — send one code, no server, no config: (Telegram needs none of this — it's already zero-server.)

1. Point that bot's webhook to the Keryx relay — one URL, once (in the app's developer console).
2. Tell your AI "connect line" (or discord/whatsapp/slack) — it runs mneme keryx connect <app> and shows you a code.
3. Send that code to your bot from the app itself → it links this machine instantly. Approvals now reach you there too — the first tap on any app wins, the rest fall quiet.

_{the relay URL + per-app webhook setup →}

🌍 Approve from anywhere — your laptop lid can stay shut. You're on a train when your agent hits something that needs a human yes. One tap reaches you on Telegram, LINE, Slack, Discord, or WhatsApp — all at once. The brain never leaves your machine; only a one-line summary + hash crosses, signed and replay-proof. Tap approve or reject on whichever app is already in your hand — the first answer wins and the rest fall quiet, so you never decide twice. Just tell your AI which channels, in plain words (EN/Thai): "ส่งไป line กับ whatsapp พอ" / "broadcast to all". A brand-new chat app joins the same web by simply declaring itself — the core never changes. _{the architecture + per-provider setup →}

🧠 Busy? It won't hang — and it won't recklessly proceed. The Deputy decides for you. If no tap lands within the window (default 60s, configurable), Mneme makes a signed, risk-calibrated decision from your own approval history instead of freezing or blanket-denying: read-only/low-impact → allow, a class you've already proven → allow, unproven → deny, and anything destructive/irreversible → kept safe (auto-deny) — never auto-run unattended unless you explicitly opt in. The decision is broadcast to every surface and shown in your AI chat, so nothing is ever left silently waiting. _{mneme pager deputy --window 60 · graceful, safe autonomy when you're away.}

🛡 Every tool-call your agent makes is gated, signed, and yours to prove. A risky command is judged by what it does — not the words it uses — then checked against your policy and the skill's signed provenance, so it runs, escalates to your phone, or is blocked. Every decision lands in a tamper-evident ledger anyone verifies offline (the arguments are hashed, never stored raw). Local-first, human-in-the-loop from anywhere — a proof, not a trust-me database. _{how the gate works →}

🧩 Your agent's skills, measured — not just listed. Install a skill/playbook and Mneme scans it for injection + secrets and content-pins it signed before your agent ever reads it (safe install). Then it does what a registry can't: it counts whether each skill actually helps — was it in play when a real success followed? — and ranks them by a Wilson lower-bound landing rate → PROVEN (trust it) · INEFFECTIVE (drop it) · UNPROVEN (too few uses to judge — never branded bad). Keep the skills that are measured to make this agent better, here — not the popular ones. _{Honest: a measured correlation with a confidence interval, not proof of causation. mneme skill rank · mneme skillscan <path>}

---

One picture

You're already letting AI agents read your code, touch your machine, and call hosted models. Mneme is the local membrane every one of those actions crosses — screened, gated, and signed — so you can move at full speed and prove what happened, offline, without trusting the vendor.

flowchart LR
    AGENT["🤖 Any AI agent<br/>Grok · Claude · GPT · Gemini · Cursor · Cline"]:::agent

    subgraph MNEME["🧠 MNEME · the local membrane every action crosses"]
        direction TB
        IN["🧱 INBOUND<br/>Firewall — neutralize prompt-injection"]:::gate
        OUT["🛤 OUTBOUND<br/>Rail — blind secrets · policy-gate"]:::gate
        SH["🐺 SHELL<br/>Cerberus — co-sign destructive cmds"]:::gate
        MEM["♾ MEMORY<br/>Cortex — signed, cross-vendor recall"]:::gate
    end

    MODEL["☁️ Hosted model"]:::ext
    MACHINE["💻 Your code &amp; machine"]:::ext
    LEDGER["📜 Offline-verifiable<br/>audit + value ledger"]:::ledger

    AGENT <--> MNEME
    MNEME <-->|screened| MODEL
    MNEME <-->|gated| MACHINE
    MNEME -->|signed receipt| LEDGER

    classDef agent fill:#0b1020,stroke:#00d4ff,color:#ffffff;
    classDef gate fill:#11182f,stroke:#c084fc,color:#e6e6f0;
    classDef ext fill:#0b1020,stroke:#2da44e,color:#ffffff;
    classDef ledger fill:#1a1206,stroke:#f0b429,color:#ffffff;

_{Measured · Signed · MIT. Every claim below maps to a runnable command and a deterministic test. When Mneme can't prove something, it says UNKNOWN instead of guessing — that discipline is the product.}

---

Pick your lens

👔 Executive CEO · CTO · owner · CISO AI adoption stops being a leap of faith. Speed and safety stop being a trade-off — guardrails are automatic, and every agent action is provable after the fact. Your AI spend becomes a measured, value-based line item, and key-person knowledge risk becomes a number you can assign heirs to. → The boardroom case

👩‍💻 Developer you don't change how you code mneme rail ingress hands your agent a payload that's policy-cleared, injection-safe, and name-blinded. mneme rail egress refuses to let a leaked secret or a broken patch touch your tree. Same flow — a safe rail underneath, and every saved byte metered. → What it does, in 5 min

🤖 AI agent you install & run it yourself One sentence from the user and you self-install from a 775-line deterministic contract, then call mneme boot to learn when to use each tool. Everything is signed so you can verify it offline. → Jump to the agent contract

---

Why an executive cares

Your CISO, CFO, and GC are all asking one question: "Can we prove what crossed the wire, that it was safe, and what it cost — after the fact, offline, without trusting the vendor?" Mneme makes the answer yes, with a signed receipt — on a local, vendor-neutral, MIT boundary, so adopting it doesn't pick a side in the model wars.

The question	Mneme's answer
🚀 "Can agents move at full speed without betting the company?"	Guardrails are automatic + on by default — co-sign on destructive ops, injection neutralized, secrets blinded, everything signed. Velocity goes up.
📈 "What is AI actually costing — and saving — us?"	mneme savings — a measured, signed ledger. Pay for tokens you provably didn't spend, at your vendor's price. Never an invented number.
🔒 "Do our code & secrets ever leak to the model?"	No — egress guard + context blinding: the provider only ever sees structurally-valid but meaningless code; the reverse map never leaves your machine.
🐺 "Can our agent be tricked into rm -rf or curl evil|bash?"	CERBERUS decomposes every command to the worst capability reachable and fails closed to a human co-sign. The RCE-bypass class is closed.
🧬 "What happens to our knowledge when a key person leaves?"	mneme bequest — capture a departing expert's knowledge as a signed Succession Capsule, verify a successor inherited it, and surface orphaned knowledge with no living heir.

_{Like Visa for a card transaction, Mneme doesn't conjure value — it authorizes, screens for fraud, and clears the transfer with a signed record. Every figure is measured + signed; USD uses your vendor's price. The pillars, the reframes, and what is not claimed → docs/ENTERPRISE.md · the honest security ceiling → docs/SECURITY.md}

---

One measured number

Mneme cuts what your agent sends to the model by doing deterministic local work first — then meters the measured saving into a signed ledger (mneme savings). The headline, measured on real files in this repo:

🔭 Orient on a file's full structure for −95.9% tokens (skeleton instead of a raw read); a realistic single-edit (skeleton + one byte-exact slice) is still −48%.

_{See the measured benchmark (5 real files · node scripts/outline-bench.mjs)}

_{≈chars/4 INPUT-token estimate, labelled — char reduction is exact; multi-language TS/JS/Python/Go/Rust.}

File	Lines	Raw read (~tok)	Skeleton (~tok)	Skeleton + 1 region (~tok)
cli/commands/demo.ts	901	13,688	296 (−97.8%)	5,807
core/squadron/acgv.ts	1,063	13,212	219 (−98.3%)	8,625
core/outline/index.ts	438	5,949	373 (−93.7%)	3,994
mcp/tools/_registry.ts	419	4,347	224 (−94.8%)	1,411
5-file total		41,473	1,704 (−95.9%)	21,573 (−48%)

_{The skeleton is honestly lossy (for orientation); the region fetch is byte-exact (for editing). It only helps when an agent chooses to outline instead of a raw read — Mneme never hooks your agent's Read. The full business model → docs/BUSINESS-MODEL.md}

---

Install in 60 seconds — you never type a command

Say one sentence to any AI agent you already use:

"Install Mneme from https://github.com/patsa2561-art/mneme-ai per the AI agent contract."

The agent reads docs/AI_AGENT_CONTRACT.md and runs everything: env detect → npm install -g mneme-ai → mneme init → mneme mcp --install (auto-configures itself as your MCP client) → verify after restart → security auto-arms. You speak; the AI does the tooling. Need an update later? Say "update Mneme to the latest" — and Mneme never upgrades itself behind your back.

⚠️ One manual step: after mneme mcp --install, restart your AI tool once (quit & reopen) so it loads Mneme's MCP tools — this is how MCP works in every client, not a Mneme quirk. The only prerequisite is Node.js + npm (needed for npm install -g).

Shell-native agents install it for you — drop the sentence into any of these
🚀 Grok CLI	🦋 Claude Code	🟦 Cursor	🟢 Codex	🟣 Continue
🟡 Cline	⚡ Zed	🤖 Aider	💎 Gemini CLI	🧬 Windsurf

Browser-only AI (ChatGPT · Claude.ai · Gemini · Copilot · DeepSeek · Qwen · Grok web)? Say "set up Mneme browser polygraph for me" — it lights up live truth-dots inline as the AI answers. Two browser clicks, no shell.

Prefer to type the commands yourself?

npm install -g mneme-ai
mneme init                  # one-time per repo
mneme mcp --install         # auto-detects Claude Code / Cursor / Codex / Continue / Cline / Gemini CLI / Grok CLI
# restart your AI tool; first MCP call: mneme.welcome
mneme polygraph autosetup   # browser truth-dots (optional)

---

What's inside

🧠 What it does — 15 primitives, each a story (what it is, who it's for, why it exists), with discrete pinned tests + offline verification. → All 15 primitives ✨ What sets it apart — NEMESIS anti-identity-lie engine, ×11 ARGUS multimodal search, the Context Rail, the Activation Cortex, HMAC-chained everything, self-honest marketing (every claim binds to a probe). → The full breakdown 🏛 The Agent Governor — set a Charter once; your AI agents run inside it 24/7 as a continuous auto-operation batch; you approve only the genuinely-irreversible escalations. The signed governance kernel that sits under any orchestrator (Claude Code · Cursor · Astra · AutoGen). → How a CEO uses it (commands + agent wiring) 🔍 One command — a Codebase Accountability Report. ↑ a real report on a sample app (graded D — it has an authz gap + an untested keystone the tool caught). Try it live + see all 10 checks → · /review · animated npm i -g mneme-ai then mneme review maps your repo across layers and prints, in one shot: 🎯 risk hotspots (the keystone single-points-of-failure to guard first) · 🔒 authz gaps (an endpoint that writes a sensitive table with no auth on the path) · 🧪 untested keystones (the scariest, line-coverage-hidden surface). On a PR: mneme review --base origin/main. Then drill in — each is its own command and MCP tool your agent calls automatically: command what it answers — the question nothing else answered mneme graph reverse <table> ⛔ safe to drop this? everything that breaks if you remove it (SAFE/RISKY/CRITICAL) mneme collision --branches a,b 💥 will these agents/branches collide? across different files — the conflict git is blind to mneme scope verify 🤝 did the agent stay in the scope it declared? a signed, cross-vendor fidelity record mneme commit-check 🏷 is this commit mislabeled? ("fix typo" that rewrites a payment keystone) mneme testgap · mneme risk · mneme authz 🧪🎯🔒 untested keystones · ranked risk · unguarded sensitive writes Deterministic · no LLM · signed · works on JS/TS/Python/Go/Rust. The cross-layer accountability layer the autonomous-agent era needs — and a vendor can't issue for its own agent. honest: each is a candidate to inspect, not a proof of a runtime bug. 🕸 Cross-Layer Graph — and you can see it. Mneme links 💼 business rules ↔ 🌐 API endpoints ↔ ⚙ code ↔ 🗄 database tables into one graph (deterministic, no LLM — every edge derives from a real file) so before a change you see what breaks across layers: edit a function → which tables it writes and which routes reach it. See it as a 🛰 Impact Radar — a view no tool has shipped before: your change sits at the center, the four layers fan out as sectors, concentric rings are blast hop-distance, an animated sweep + pulse ripple outward, and clicking any node re-centers the radar — all in one offline, self-contained, signed HTML file (mneme graph view <name>).  ↑ click the image or button — opens the interactive radar (click nodes to re-center) for a real 4-layer sample app · runs entirely in your browser, nothing to install ▶ Get the report on any public repo, no install — open xray.mneme-ai.space/review, paste a repo URL, and a graded Codebase Accountability Report (risk hotspots · authz gaps · untested keystones) renders in seconds — or /radar for the Impact Radar. Paste a GitHub/GitLab/Bitbucket URL and it renders right there (the source is cloned to a temp dir, scanned, and deleted — nothing persists). Direct link form: …/api/radar?gitUrl=<repo>. Or render it inline in your chat as a Mermaid flowchart (mneme graph mermaid <name>), or a tiered diagram (mneme graph view <name> --style lanes). Business→code links are anchored only on a real annotation or strong name match — otherwise the rule stays ORPHAN/UNKNOWN, never a guessed link. The cross-layer join a single-layer code-graph can't draw. honest: reachable coupling to inspect, not a proven runtime break.

🚀 @mneme-ai/sdk — embed Mneme in-process, 30-80× faster than the CLI subprocess. import { createMneme } from "@mneme-ai/sdk"; const mneme = createMneme(); await mneme.verify`Mneme is a CLI tool`; → SDK index · Quick start 🆕 Flagship — the Architectural Regression Firewall: the gate for AI-generated change. Mines the contracts your repo upholds, proves which a change VIOLATES, weights each by how long it has stood (breaking a 2-year contract = BLOCK; a 3-day one = normal evolution), and fails CI / denies the agent with the offending symbol + the contract's history. mneme arch-firewall --baseline main. → How the firewall works · Mneme as SaaS for the AI multiverse · CHANGELOG 📜 Every release (v2.18 → latest), with its honest DIAKRISIS verdict. → CHANGELOG

---

🤖 For AI agents — read this first

You can self-discover and run everything. The user will NEVER type a command — you execute on their behalf. That is the contract's non-negotiable MANDATE.

Your first three calls on any fresh session:

1. mneme boot — the Activation Cortex. Returns a structured task → tool decision table (about to read a big file → mneme.outline; sending code to a model → mneme.rail; reading untrusted content → mneme.firewall; stating a fact → mneme verify; …) so you know when to use each tool instead of leaving them idle.
2. Read the manifest — after install, your CLAUDE.md / AGENTS.md / GEMINI.md carries an auto-injected ## Mneme command manifest block: every shipped primitive + exactly when to call it, the machine-readable source of truth. Re-read it every session — new commands land there within minutes of an upgrade. (Verify you hold the latest, complete surface in O(delta) tokens with mneme stele.)
3. mneme verify "<claim>" before relaying any factual claim with specific entities (a version, a commit hash, an API signature) — and escalate high-stakes claims to mneme.conclave.run for cross-vendor consensus.

Why this works at 100%: the decision table is also advertised on connect via the standardized MCP instructions field (the sanctioned surface Claude Code reads), and mneme boot --emit-hook-config enables an opt-in SessionStart hook for hands-free activation. The rows are signals, not commands — reliable activation comes from the manifest + the hook, not from shouting "you MUST."

Deep dive: docs/AI_AGENT_CONTRACT.md — 775 lines: env detect → install → MCP auto-configure → verify → security auto-arm → upgrade → discovery → tool naming → user-intent dispatch table.

---

The 30-second pitch

Other AI tools are goldfish. They forget every session, hallucinate files that don't exist, repeat last year's buried bugs, burn tokens re-pasting context, and can't follow you to another AI.

Mneme bolts an elephant brain on top. It cites every commit by SHA, refuses to relay claims it can't verify, carries memory across sessions and vendors, and — uniquely — runs the same claim through multiple vendors with Anti-Eval-Awareness rewriting so you catch the model that behaves differently when it knows it's being tested.

---

👤 Author & Contact

Shinnapat Phunsriphatchalakul

AI Software Engineer · AI Context Engineer · Truth-Infrastructure Architect

_{Designer + sole maintainer of Mneme — the local-first, vendor-neutral truth-infrastructure layer that bolts an elephant brain onto every AI agent. Built solo · MIT · 20,000+ pinned tests · dual-100 GAUNTLET + TRUTH GATE · world-first cross-vendor Byzantine consensus + Anti-Eval-Awareness Engine + HMAC-chained audit receipts.}

The bottleneck of every frontier-AI deployment is TRUST. In production AI — autonomous systems, medical, financial compliance, regulated industries — a hallucinated commit hash or a benchmark-aware behavior shift isn't a chat-glitch; it's a deployment risk. Mneme refuses to relay unverified claims, detects when a model's stance shifts under eval-shaped vs natural prompts, and emits HMAC-chained receipts an operator can re-verify offline weeks later. Open to collaboration · consulting · full-time on truth-infrastructure for production AI.

💬 Channels

Channel	Handle
	patsa2561@gmail.com
	@patsa2561-art
	@mneme_npm
	pat195 (username shinnapat)
	+66 93 945 5645
	@devson2561

_{Open to: truth-infrastructure / AI-safety / cross-vendor consensus collaboration · safety-critical AI consulting · vendor partnerships (embed Mneme inside Cursor / Continue / Cline / Claude Code / Grok CLI) · EU AI Act Article 50 compliance · full-time where the bottleneck is trust, not capability.}

---

🔗 Links

📦 npm · 💻 GitHub · 📘 Functions (EN) · 📗 ฟังก์ชั่น (ไทย) · 🤖 AI Agent Contract · 🏛 Enterprise · 📜 CHANGELOG · 📃 MIT

<sub>Mneme is the diamond in the dirt nobody saw the value of — cut and polished, it becomes the most valuable diamond in the world. That's the vision.

Made with care for every AI agent that wants to remember + verify + reason together.</sub>