mnemo
mnemo
Persistent memory for AI coding agents.
Give Claude Code, Codex, Cursor, Windsurf, OpenCode, fx and Pi one shared local memory that survives sessions, compactions and agent switches.
Quick Start · Why mnemo? · Agents · Docs · Roadmap
What is mnemo?
mnemo is a local memory layer for agentic development. It stores decisions, bugs, conventions, discoveries and session summaries in SQLite, then exposes them back to agents through MCP tools, hooks and portable Agent Skills.
Instead of spreading project knowledge across MEMORY.md, native editor memory, chat transcripts and human notes, mnemo gives every supported agent the same project-scoped source of truth.
Quick Start
Install the binary and configure your detected agents:
curl -sSf https://raw.githubusercontent.com/jmeiracorbal/mnemo/main/install.sh | bash
Activate mnemo in a project:
cd your-project
mnemo init --agent=all
Check that everything is wired correctly:
mnemo doctor --agent=all --path=.
Save and search memory manually from the CLI:
mnemo save "Use SQLite FTS5" "Search stays local, fast and dependency-light." --type decision --project myapp
mnemo search "SQLite" --project myapp
Why mnemo?
| Problem | mnemo gives you |
|---|---|
| Agents forget decisions between sessions | Durable project memory in ~/.mnemo/memory.db |
| Different agents keep different memories | One shared layer for Claude Code, Codex, Cursor, Windsurf, OpenCode, fx and Pi |
| Markdown memory files drift or conflict | Structured observations, tags, topic keys and review states |
| Global hooks can be risky | Project opt-in via a .mnemo marker; projects without it are ignored |
| Setup breaks silently | mnemo doctor and mnemo setup status explain exactly what is configured |
| Duplicated projects/memories accumulate | Project merge tools and memory curation workflows |
Features
| Feature | What it does |
|---|---|
| Project-scoped activation | Global hooks only run when a project contains a valid .mnemo marker. |
| MCP tools | Agents can call mem_save, mem_search, mem_context, mem_current_project, mem_doctor and more. |
| Session hooks | Session start/end hooks register activity, inject context and capture learnings automatically. |
| Portable Agent Skills | Skills teach compatible agents when and how to use mnemo without falling back to native memory. |
| Passive capture | Extracts useful learnings from transcripts and subagent output. |
| Agent provenance | Records SQL-queryable agent, source, tool, model and MCP client metadata for writes that provide it. |
| Diagnostics | mnemo doctor checks project activation, global setup, MCP, hooks, competing memory surfaces and database migration health. |
| Database safety | Safe schema migrations run automatically; mnemo db migrate --check validates the local store for CI or troubleshooting. |
| Self-update | Released binaries check for newer releases on interactive CLI use and can confirm, download and install with mnemo update. |
| Programmable CLI | Cobra-generated help keeps the command menu and nested subcommands aligned with the executable. |
| Project maintenance | mnemo projects list, mnemo projects merge and mnemo projects rename help curate duplicate or unclear project identities. |
| Memory curation | mnemo memories review surfaces duplicate or conflicting observations for approved repair. |
Supported Agents
| Agent | MCP | Hooks / runtime | Global instructions | Skill access | Status |
|---|---|---|---|---|---|
| Claude Code | ✅ | Plugin or n/a via install.sh |
✅ | ✅ | Supported |
| Codex | ✅ | ✅ | ✅ | ✅ | Supported |
| Cursor | ✅ | ✅ | ✅ | ✅ | Supported |
| Windsurf | ✅ | ✅ | ✅ | ✅ | Supported |
| OpenCode | ✅ | ✅ | ✅ | ✅ | Supported |
| fx | ✅ | n/a | ✅ | ✅ via canonical path | Supported |
| Pi | ✅ via MCP extension | n/a | ✅ | ✅ via ~/.pi/agent/skills/ |
Supported |
Global setup is installed once. Project activation stays local and opt-in:
project/
├── .mnemo # project ID + activated agents, ignored by git
├── AGENTS.md # shared project memory authority
├── CLAUDE.md # Claude-specific rules when selected
├── .cursor/ # Cursor rules when selected
└── .pi/ # Pi prompt extensions when selected
See it in action
$ mnemo doctor --agent=all --path=.
status: ok
checks: project marker, binary, MCP, hooks, instructions, store
$ mnemo context myapp
## Memory from Previous Sessions
- Chose SQLite FTS5 for local search.
- Refresh hooks must keep executable permissions.
$ mnemo memories review --project=myapp
No potential memory conflicts found.
Installation options
| Path | Use when | Command |
|---|---|---|
| Auto installer | You want the binary plus detected agent setup | curl -sSf https://raw.githubusercontent.com/jmeiracorbal/mnemo/main/install.sh | bash |
| Explicit agent | You only want one integration | bash -s -- --agent=codex |
| All agents | You want every supported integration prepared | bash -s -- --agent=all |
| Claude plugin | You use Claude Code’s plugin marketplace | claude plugin install mnemo@mnemo |
| Source build | You develop mnemo itself | go build -o ~/.local/bin/mnemo ./cmd/mnemo/ |
Read the complete setup guide in docs/INSTALLATION.md.
Updates
Released mnemo binaries check GitHub Releases during interactive CLI use. When a newer release exists, mnemo itself prints the installed/latest versions and asks before changing anything:
mnemo update
mnemo update --yes --agent=all
mnemo update --check --json
mnemo update downloads the official installer, pins it to the detected latest
release and refreshes mnemo’s agent integration files after installing. It does
not update Claude Code, Codex, Cursor or other agent applications themselves.
Restart active agent sessions after updating so they reload the refreshed
binary, hooks and skills. Update checks are skipped in MCP, hook and JSON-output
paths so integrations remain machine-readable.
Codex hook review
Codex protects every hook in ~/.codex/hooks.json with an interactive trust
review. mnemo currently installs Codex SessionStart and Stop hooks; the same
Codex trust mechanism will also apply whenever a mnemo-owned hook is added or
its command changes.
If Codex says a mnemo hook needs review, or if mnemo setup status --agent=codex
shows the Codex Hooks column as no, open Codex normally and approve the
interactive hook prompt (press a or follow the prompt shown by Codex). Codex
will then write the matching trusted_hash entries under [hooks.state] in
~/.codex/config.toml. Re-run:
mnemo setup status --agent=codex
mnemo doctor --agent=codex --path=.
to confirm the Codex hooks are trusted and active. Do not manually copy hashes between machines; approve hooks in the Codex UI so the hash matches the local hook command.
Cloud sync
mnemo can replicate local memory to a Turso/libSQL cloud database so multiple machines or agents share the same observations. Configure credentials once:
mnemo setup cloud
Credentials are stored in ~/.config/mnemo/cloud.toml (XDG). Environment variables MNEMO_CLOUD_URL, MNEMO_CLOUD_KEY, and MNEMO_CLOUD_CLIENT_ID override the file when set. Sync is local-first and idempotent — the local SQLite store is always the operational copy.
mnemo sync run # push, then pull
mnemo sync status # inspect local sync state without contacting cloud
mnemo setup cloud --validate # test credentials without modifying them
See docs/CLOUD_SYNC.md for the full reference.
Documentation
| Guide | Contents |
|---|---|
| Documentation index | Full documentation map and research notes. |
| Installation | Install script, plugin setup, project activation and verification. |
| Agent integration | Hook behavior, global paths, .mnemo marker and Agent Skills. |
| CLI reference | Commands, examples, MCP tools and search modes. |
| Troubleshooting | doctor, setup status, manual checks and idempotency validation. |
| Storage | SQLite location, schema notes and sqlc workflow. |
| 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.
- Repairable: duplicate project identities and memory conflicts are visible and fixable through CLI primitives.
License
Apache 2.0: you may use, modify, and distribute freely, but must retain the copyright notice and include the NOTICE file in all distributions.