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: ```bash curl -sSf https://raw.githubusercontent.com/jmeiracorbal/mnemo/main/install.sh | bash ``` Activate mnemo in a project: ```bash cd your-project mnemo init --agent=all ``` Check that everything is wired correctly: ```bash mnemo doctor --agent=all --path=. ``` Save and search memory manually from the CLI: ```bash 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
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](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:
```bash
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:
```bash
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:
```bash
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.
```bash
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](docs/CLOUD_SYNC.md) for the full reference.
## Documentation
| Guide | Contents |
|---|---|
| [Documentation index](docs/README.md) | Full documentation map and research notes. |
| [Installation](docs/INSTALLATION.md) | Install script, plugin setup, project activation and verification. |
| [Agent integration](docs/AGENT_INTEGRATION.md) | Hook behavior, global paths, `.mnemo` marker and Agent Skills. |
| [CLI reference](docs/CLI.md) | Commands, examples, MCP tools and search modes. |
| [Troubleshooting](docs/TROUBLESHOOTING.md) | `doctor`, `setup status`, manual checks and idempotency validation. |
| [Storage](docs/STORAGE.md) | SQLite location, schema notes and sqlc workflow. |
| [Roadmap](ROADMAP.md) | 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](LICENSE): you may use, modify, and distribute freely, but must retain the copyright notice and include the [NOTICE](NOTICE) file in all distributions.