Mnema
felipesauer/mnema
Auditoria imutável e local-first para trabalho de agentes IA
Ver no GitHubMCP server local-first para auditoria à prova de falsificação de trabalho executado por agentes IA. Implementa um log criptograficamente encadeado em SHA-256, mantém humanos no controle via gates de workflow tipados, e garante rastreabilidade total de quem autorizou, qual agente executou e em qual run.
Instalação
npx convez-ai felipesauer/mnema1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Auditoria de operações realizadas por agentes Claude Code, Cursor ou Aider
- Rastreamento de conformidade e chain-of-custody em processos automatizados
- Validação de integridade de mudanças em repositórios gerenciados por IA
Veredito

Mnema resolve um problema real e negligenciado: prova criptográfica de que agentes IA executaram exatamente o que foi autorizado, sem desvios ou falsificação posterior. Implementação sólida em TypeScript com verificação de integridade de cadeia hash e workflow gates tipados — essencial para contextos regulatórios ou alta confiança.
README
A tradução para o português deste README ainda está na fila.
Mnema
A tamper-evident, local-first audit trail for AI-agent work. You drive, agents execute — and you can prove what happened.
Mnema is a local-first MCP server that gives external AI agents (Claude Code, Cursor, Aider, …) typed tools to do work behind workflow gates, while every action lands in a SHA-256 hash-chained audit log that records who coordinated, which agent executed, and in which run. Humans drive through the terminal and verify through the history. Mnema does not run agents — it makes their work accountable.
Not a semantic-memory layer. Mnema does not do embeddings or similarity recall — if you want an agent to remember facts across sessions, reach for Mem0 or Cognee. Mnema answers a different question: what did the agents do, who authorized it, and can you prove the record wasn't altered? It pairs cleanly with a memory layer; it doesn't replace one.
Table of contents
- Why Mnema
- Quickstart
- Install
- What you get
- How the MCP loop works
- Project layout after
mnema init - Common CLI commands
- Configuration
- Workflows
- Status
- Getting help
- Further reading
- License
Why Mnema
When an AI agent works in your repository, three questions usually go unanswered: what exactly did it change, did it skip the steps it was supposed to follow, and can you trust the record after the fact? Mnema answers all three.
- It makes agent work provable. Every mutation appends to a
SHA-256 hash-chained audit log. Change one past entry and the chain
breaks —
mnema doctorcatches edits, truncation, replays, and deletion. This is the part most agent tooling doesn't have. - It keeps the human in the loop. Agents move work through a workflow whose gates reject invalid transitions (no submitting a task with no acceptance criteria, no skipping review). You approve through the terminal; the agent can't route around you.
- It records who did what. Each event carries a dual identity — the human who coordinated, the agent that executed, the run it belonged to — so the history reads like a chain of custody.
- It stays yours. Local-first, zero telemetry, no remote services. SQLite + plain-text Markdown/JSONL in your repo; the files outlive Mnema and open in any editor.
| Instead of… | …you get |
|---|---|
| A task tracker with no cryptographic guarantee the log is intact | A tamper-evident hash chain with doctor verification |
| A semantic memory layer (Mem0, Cognee) that recalls facts | A provable record of actions taken, not facts remembered |
| A heavyweight Jira/web UI | An MCP server + CLI that lives next to your code |
| Free-form agent prose you have to trust | Typed tools behind workflow gates that reject bad input |
Quickstart
Status: Mnema is published on npm as an alpha (see Install). The surface is feature-rich and is still being hardened toward a stable
1.0.
# 1. Install and initialise a project
npm install -g @felipesauer/mnema@alpha
cd my-project
mnema init --name "My App" --key "MYAPP"
# 2. Wire your AI client to the MCP server
mnema mcp install-instructions claude-code
Step 2 prints the exact registration command and config for your client. For Claude Code it looks like this:
Register with `claude mcp add` (preferred), or paste the JSON
below into ~/.claude.json under `mcpServers`:
claude mcp add mnema -s user -e MNEMA_AGENT_HANDLE=claude-code -- mnema mcp serve
Run that claude mcp add line, restart your client, and confirm the
project is healthy:
mnema doctor # all checks green on a fresh project
From here your agent drives Mnema through MCP tools, and you watch and approve from the terminal — walked through end to end in How the MCP loop works.
What you get
| Surface | What it does |
|---|---|
| Audit log | Every action appends to a SHA-256 hash-chained JSONL log (mirrored to SQLite). mnema doctor detects edits, truncation, replays, and deletion. |
| Workflow gates | A state machine per task; each transition declares required fields and Mnema rejects invalid moves. |
| Agent runs & plans | Wrap every batch of mutations in a run (parent/child, max depth 5); inspect any run later via the CLI. |
| Dual identity | Each event records the human actor, the agent that executed, and the run — a built-in chain of custody. |
| Tasks, sprints, epics | Full work tracking: tasks with acceptance criteria/estimate/assignee, one active sprint per project, epics grouping tasks. |
| Decisions (ADRs) | proposed → accepted/rejected → superseded chains, with a shortcut to promote a note into a decision. |
| Full-text search | Search across tasks, decisions, notes and more — case- and accent-insensitive. |
| Attachments | Files attached to a task or decision, deduplicated by content hash. |
| Skills, memories, observations | Human-curated knowledge the agent records via MCP tools, mirrored to plain .md files (not semantic recall — see the note above). |
| Workflows | 4 presets (default, lean, kanban, jira-classic) plus custom JSON validated against a schema. |
| MCP tools | 30+ universal tools plus one per workflow action; context_bootstrap is the canonical session entry point. |
Install
The Quickstart above covers the common path
(npm install -g @felipesauer/mnema@alpha). A few platform notes:
- Alpha releases live under the
alphadist-tag, so install with@alphato be explicit about what you're getting. (Until the first stable1.xships,latestalso points at the current alpha.) - The native SQLite binding (
better-sqlite3) installs a prebuilt binary with npm/npx — no compiler needed. With pnpm, runpnpm approve-builds better-sqlite3afterwards (pnpm blocks build scripts by default). Platforms without a prebuilt binary need a C++ toolchain (python3,make,g++).
To work from source instead:
git clone https://github.com/felipesauer/mnema.git
cd mnema
pnpm install
pnpm build
ln -s "$PWD/mnema" /usr/local/bin/mnema # optional, for global access
mnema --version
The bundled ./mnema shell script forwards to dist/index.js —
useful for dogfooding without a global install.
Adopting an existing project
You don't have to start clean. mnema init --minimal then
mnema adopt all eases Mnema into a repo that already has work, and
mnema import markdown / mnema import github-issues pull legacy
items in.
Project layout after mnema init
my-project/
├── AGENTS.md # operating manual for agents (versioned)
├── .gitignore # pre-seeded ignores for local state
└── .mnema/ # everything Mnema owns
├── mnema.config.json # project configuration (versioned)
├── audit/ # append-only event log (versioned by default)
│ └── current.jsonl
├── state/ # local cache — gitignored
│ └── state.db # SQLite (FTS, tasks, runs, audit metadata)
├── backlog/ # one folder per workflow state
│ ├── DRAFT/MYAPP-1.md
│ ├── READY/
│ └── …
├── sprints/ # sprint planning notes
├── roadmap/ # quarterly / theme docs
├── memory/ # human-curated context (decisions, notes)
├── skills/ # agent-recorded skills, mirrored to .md
└── workflows/
└── default.json # active state machine
Common CLI commands
| Command | What it does |
|---|---|
mnema init | Create the full layout (use --minimal for adoption) |
mnema adopt <component> | Add skills/, memory/ or roadmap/ later |
mnema task create / list / show / move | Manage tasks |
mnema sprint plan / start / close / show / add | Manage sprints |
mnema search <query> | Full-text search across the project |
mnema attach add <task> <file> | Attach a binary, deduped by SHA-256 |
mnema history --since=today | Compact human activity view |
mnema watch | Live tail of mutations |
mnema inbox | Tasks awaiting review or blocked |
mnema agent inspect <run_id> | Detail of an agent run with its plans and mutations |
mnema audit query [filters] | Raw audit log access |
mnema sync | Rebuild the SQLite cache from the markdowns |
mnema doctor | Read-only diagnostic check |
mnema skill lint | Validate skills/ files (frontmatter, MCP tool refs, examples) |
mnema memory consolidate | Regenerate the INDEX.md files under memory/ |
mnema import markdown --from PATH | One-shot import from ## STATE Title headings |
mnema import github-issues --repo OWNER/REPO | One-shot import from GitHub Issues |
mnema mcp serve | Start the MCP server on stdio (called by your AI client) |
mnema mcp install-instructions <client> | Print the right config snippet |
Run mnema <command> --help for full flags and examples.
How the MCP loop works
- Your AI client (Claude Code, Cursor, …) spawns
mnema mcp servewithcwdpointing at your project. Configure it once viamnema mcp install-instructions claude-code(the printed snippet already includes the rightagent_handle). - The agent calls
context_bootstrapfirst — it gets the project identity, active workflow, recent decisions and pointers to memory. - Before any mutation it calls
agent_run_start({ goal })— without an active run, mutations are rejected withNO_ACTIVE_RUN. - It then uses
task_create,task_submit,task_block, … as the workflow allows. Every transition is validated against the gate (task_submitrequirestitle,description,acceptance_criteria,estimate). - When done,
agent_run_end({ status: "completed" })flushes the sync buffer and closes the run.
A concrete pass
An agent asked to "add a rate limiter" might: start a run, create
MYAPP-12, submit it through the gate (which forces acceptance
criteria and an estimate), move it to IN_PROGRESS, do the work,
then submit it for review. It cannot mark its own task DONE — the
default workflow routes that through your approval. Meanwhile you
watch and inspect from the terminal:
mnema watch # live tail of every mutation
mnema inbox # what's waiting on your review
mnema history --since=today # formatted activity log
mnema agent inspect <run_id> # one run, with its plans + mutations
mnema doctor # re-verify the audit chain anytime
Approve with mnema task move MYAPP-12 approve, and the whole
sequence — who, which agent, which run, in what order — is sitting in
the hash-chained audit log, verifiable forever.
Configuration
.mnema/mnema.config.json is the only configuration. Minimal fields:
{
"version": "1.0",
"mnema_version": "^0.4.0-alpha.0",
"project": { "key": "MYAPP", "name": "My Application" },
"workflow": "default"
}
Optional fields cover custom paths, audit retention, sync flush
thresholds and feature flags. Run mnema doctor after editing — it
re-validates the file against the schema and reports anything that
drifted.
Workflows
Workflows are JSON files in workflows/. The default ships with
seven states — DRAFT → READY → IN_PROGRESS → IN_REVIEW → DONE,
with BLOCKED and CANCELED branches. Each transition declares
its gate (which fields are required, with min/max/enum/format
constraints expressed in a small JSON DSL) — Mnema translates the
gate into Zod at boot time and surfaces one MCP tool per transition.
To switch presets, edit workflow in mnema.config.json and run
mnema doctor. To author a new workflow, copy
workflows/default.json and tweak.
Status
Mnema is alpha and published on npm. The
accountability core is the differentiator and it is in place: a
SHA-256 hash-chained audit log with doctor tamper-detection
(edits, truncation, replays, deletion), dual-identity capture
(human actor + agent + run) on every event, workflow gates that
reject invalid transitions, and optimistic-concurrency lost-write
protection in every mutation. Around it the full surface is built —
tasks, sprints, decisions, notes, epics, attachments, FTS search,
agent runs & plans, 9 skill/memory/observation MCP tools, 4 shipping
workflows (default, lean, kanban, jira-classic), and a
workflow schema with cross-cutting refines. The package keeps being
shaken out via adversarial sweeps (audit immutability, multi-actor
concurrency, custom workflow validation) and an end-to-end 21-phase
smoke suite on the way to a stable 1.0.
436 tests, 0 skipped, lint + build clean. Every release passes a 13-check publish gate (scripts/publish-check.sh) plus a 21-phase manual smoke before tagging. See CHANGELOG.md for the per-version history.
Getting help
- Bug or unexpected behaviour? Open an issue — the bug-report
template asks for
mnema --version, repro steps, and (if relevant) a snippet of.mnema/audit/current.jsonl. - Question or idea? Use GitHub Discussions.
- Security issue? Report it privately — see SECURITY.md.
- Want to contribute? Start with CONTRIBUTING.md.
Further reading
- CHANGELOG.md — per-version history, with rationale for every notable change.
- CONTRIBUTING.md — dev setup, commit conventions, smoke run, and what to watch out for when touching the schema, the audit log, or the workflow.
- AGENTS.md (generated by
mnema init) — the contract a fresh AI agent reads on session start so it knows how to drive Mnema responsibly.
License
MIT © Felipe Sauer