Mnemo

Mnemo is an open-source, local-first context runtime for coding agents. It keeps project facts, decisions, constraints, tasks, failed approaches and Git-aware checkpoints outside any individual model, then compiles only the relevant context for the next session.

The model can change. The project memory remains.

Why Mnemo

Coding sessions are temporary, but project decisions are not. Mnemo provides a small continuity layer shared by Codex, Claude Code, Gemini CLI and any MCP-compatible client:

developer → Mnemo → relevant context → coding agent → checkpoint → Mnemo

Mnemo is not an IDE, hosted service or coding agent. The core works offline and stores data inside the project.

Requirements

• Node.js 22 or newer
• Git is recommended, but not required
• At least one supported agent CLI for ctx <agent>

Install

During development:

pnpm install
pnpm build
npm link

After publication:

npm install -g mnemo-context-runtime

Quick start

cd my-project
ctx init
ctx task "Implement authorization" "Add server-side role checks"
ctx decide "Identity key" "Use immutable provider subject, never email"
ctx constrain "Authorization boundary" "Every object access is checked server-side"
ctx checkpoint "Authorization foundation"
ctx codex

Running ctx without an agent opens a selector containing the installed agent CLIs.

For the complete command sequence in Portuguese, see GUIA_DE_USO.md.

Commands

Command	Purpose
ctx init	Create .context/ and the local SQLite database
ctx	Select an installed agent and inject compiled context
ctx codex / claude / gemini	Start one agent with the current context
ctx remember	Record a durable fact
ctx decide	Record an active decision
ctx constrain	Record a critical constraint
ctx task	Record the current or next task
ctx fail	Record a failed approach and resolution
ctx checkpoint	Snapshot Git state and project continuity
ctx context	Print the token-budgeted context package
ctx why <topic>	Retrieve memory related to a decision or topic
ctx status	Show active memory and checkpoint state
ctx doctor	Diagnose runtime and agent availability
ctx mcp	Serve project memory using MCP over stdio

Use ctx <command> --help for command-specific options.

Storage

Mnemo creates:

.context/
├── config.json
├── context.db
├── state.json
└── logs/

.context/ should not be committed. Project configuration stays local, and SQLite uses WAL mode, foreign keys and prepared statements.

Security model

All text is sanitized before persistence. Built-in rules redact common API keys, bearer credentials, JWTs, private keys and password-like assignments. .contextignore documents files that must not enter repository analysis.

Sanitization is defense in depth, not a reason to paste credentials into Mnemo. Never deliberately record secrets.

MCP setup

Any MCP client that supports local stdio servers can launch:

{
  "mcpServers": {
    "mnemo": {
      "command": "ctx",
      "args": ["mcp"]
    }
  }
}

Available tools include project_state, project_context, memory_search, memory_get, report_memory and memory_checkpoint.

Design principles

• Git owns code history; Mnemo owns continuity and rationale.
• Active decisions supersede old decisions instead of silently rewriting history.
• Context cost grows with changes, not the full conversation history.
• Local rules and deterministic inspection come before optional model inference.
• An agent receives a minimal package first and retrieves more context on demand.

Development

pnpm typecheck
pnpm test
pnpm build

See PROJETO.md for the product definition and IMPLEMENTATION.md for release status.

Benchmark

The first controlled handoff experiment is documented in benchmarks/devtrace-saas/RESULTS.md. It observed an 18% reduction in uncached-input-plus-output tokens with equivalent typecheck/test outcomes. This is an initial paired run, not yet a statistically reliable performance claim; the protocol requires at least five repetitions.

License

Apache License 2.0.