mnemo

Same source of truth across Claude Code, Codex, Cursor, OpenCode and Pi.

English · Español · 简体中文

Quick Start · Why mnemo? · How it works · Agents · Docs · Community · Roadmap

---

Why mnemo?

Agents forget. Markdown memory drifts. Hooks race. Setup fails silently.

Without mnemo	With mnemo
Decisions vanish between sessions	Durable project memory in local SQLite
MEMORY.md, editor memory and chat notes diverge	One project-scoped source of truth for every supported agent
Global hooks run everywhere, or nowhere useful	Opt-in via .mnemo; unmarked projects are ignored
Silent misconfiguration	mnemo doctor explains exactly what is wired; mnemo doctor --fix repairs it

mnemo does not claim every harness. It ships a stable memory contract that any harness can implement and validate.

Quick Start

# 1. Install the latest stable release
curl -sSf https://raw.githubusercontent.com/jmeiracorbal/mnemo/main/install.sh | bash

# 2. Activate in a project
cd your-project
mnemo init --agent=all

# 3. Verify
mnemo doctor --agent=all --path=.

Then in your agent: mem_save a decision, close the session, open another — mem_search / mem_context finds it.

mnemo search "SQLite" --project "$(mnemo json id < .mnemo)"

The installer and mnemo update follow the latest published stable release (v1.0.0). Use mnemo update --prerelease only to opt into prereleases. See the Installation guide for updates and agent-specific setup.

How it works

1. Agents talk to mnemo through MCP tools, hooks and portable Agent Skills.
2. A local event controller is the sole normal SQLite writer — publishers never open the database.
3. Memories stay on your machine: structured observations, tags, topic keys and session summaries in SQLite + FTS5.

project/
├── .mnemo      # project ID + activated agents (gitignored)
├── AGENTS.md   # shared memory authority
├── CLAUDE.md   # Claude rules when selected
├── .cursor/    # Cursor rules when selected
└── .pi/        # Pi prompt extensions when selected

See Durable Events for delivery and failure semantics.

Highlights

• Project-scoped activation — global hooks stay inert without a valid .mnemo
• MCP + native tools — mem_save, mem_search, mem_context, mem_doctor, and more
• Durable event controller — JetStream per user; idempotent SQLite transactions
• Controller-owned sessions — agent-native execution IDs bind to one canonical session
• Portable skills — teach agents to use mnemo instead of falling back to native memory
• Passive capture — extract learnings from agent-provided output
• Provenance — SQL-queryable agent, tool, model and MCP client metadata
• Diagnostics & repair — mnemo doctor / mnemo doctor --fix, project merge/rename, mnemo memories review
• Safe migrations & self-update — schema upgrades on open; mnemo update for releases

Supported Agents

Agent	MCP	Hooks / runtime	Global instructions	Skill	Status
Claude Code	Yes	Session hooks	Yes	Yes	Supported
Codex	Yes	Session hooks	Yes	Yes	Supported
Cursor	Yes	Prompt hook	Yes	Yes	Supported
OpenCode	Yes	Plugin events	Yes	Yes	Supported
Pi	Native tools	Native extension	Yes	Yes	Supported

Codex requires an interactive hook trust review after install — details in Agent Integrations.

Claude Code uses CLAUDE_CONFIG_DIR for its config directory when set, and defaults to ~/.claude. Its MCP configuration .claude.json lives in that directory when CLAUDE_CONFIG_DIR is set, and in $HOME otherwise.

Associated modules

Module	Purpose
mnemo-adapters	Agent adapter interfaces and mappings for CLI, controller and MCP
mnemo-events	Durable event and command contracts shared by publishers, controller and store

Installation options

Path	Command
Pinned stable (v1.0.0)	curl -sSf https://raw.githubusercontent.com/jmeiracorbal/mnemo/main/install.sh | MNEMO_VERSION=v1.0.0 bash
Latest stable	curl -sSf https://raw.githubusercontent.com/jmeiracorbal/mnemo/main/install.sh | bash
One agent	bash -s -- --agent=codex
All agents	bash -s -- --agent=all
From source	go build -o ~/.local/bin/mnemo ./cmd/mnemo/

The installer configures every agent: instructions, MCP server, hooks and skills. mnemo ships no agent plugins. If you installed the mnemo Claude Code or Codex plugin from an earlier release, mnemo doctor reports it and mnemo doctor --fix removes it and restores the installer setup.

Full update flags and uninstall steps: Installation.

Documentation

Guide	Contents
Wiki home	User documentation and navigation
Installation	Binary, controller, activation, updates
Agent integrations	Native IDs, hooks, tools, Codex trust
Durable events	Controller architecture and failure behavior
CLI reference	Commands, MCP tools, search modes
Troubleshooting	Diagnostics and controller recovery
Storage	SQLite, migrations, sqlc
Roadmap	Planned product and maintenance work

Design principles

• Local-first — memory stays on your machine in SQLite
• Agent-neutral — one memory authority across supported coding agents
• Opt-in by project — global integrations are inert without .mnemo
• Diagnosable — every setup surface can be checked without mutation, and mnemo doctor --fix repairs it
• Repairable — duplicate projects and memory conflicts are visible and fixable via CLI

Community

Star the repo if mnemo helps your agent workflow — it signals that local, agent-neutral memory is worth building.

• Contributing — build, test, and open a PR
• Code of Conduct — community standards
• Security — private vulnerability reporting
• Site · Wiki · Roadmap

License

Apache 2.0: use, modify and distribute freely; retain the copyright notice and include NOTICE in all distributions.