mnemo

mnemo

Persistent memory for AI coding agents. mnemo stores decisions, bugs, conventions, and discoveries across sessions in a local SQLite database.

The integration is per-project and opt-in. Hooks fire globally on every session, but they only activate when the project contains a .mnemo marker. Run mnemo init once from a project root to enable mnemo there. Projects without the marker are unaffected.

Prerequisite: binary in PATH

The mnemo binary must be in your PATH before any agent integration will work. This applies to Claude Code, Cursor, Windsurf, and Codex regardless of how the integration is installed.

The hooks that fire on session start, session end, and passive capture all call mnemo directly. The MCP server is also the mnemo binary. Without it in PATH, hooks fail silently and the MCP server cannot start.

Install the binary:

curl -sSf https://raw.githubusercontent.com/jmeiracorbal/mnemo/main/install.sh | bash

Or build from source:

git clone https://github.com/jmeiracorbal/mnemo
cd mnemo
go build -o ~/.local/bin/mnemo ./cmd/mnemo/
export PATH="$HOME/.local/bin:$PATH"

Verify:

mnemo --version

Features

• Session hooks: starts/ends sessions and injects memory context at the beginning of every conversation
• 18 MCP tools: mem_save, mem_search, mem_context, mem_tag_stats, and more, available directly inside your editor
• Passive capture: extracts learnings from conversation transcripts automatically at session end
• Full CLI: save, search, export, import, and inspect memories from the terminal
• Own storage: isolated ~/.mnemo/memory.db, created automatically on first run
• Claude Code + Cursor + Windsurf + Codex: native integration for all four agents via their respective hook systems

Setup: two phases

Phase 1 — install globally (once per machine):

# Claude Code (via plugin — recommended)
claude plugin marketplace add jmeiracorbal/mnemo
claude plugin install mnemo@mnemo

# or via install.sh for any agent:
curl -sSf https://raw.githubusercontent.com/jmeiracorbal/mnemo/main/install.sh | bash -s -- --agent=claudecode
curl -sSf https://raw.githubusercontent.com/jmeiracorbal/mnemo/main/install.sh | bash -s -- --agent=cursor
curl -sSf https://raw.githubusercontent.com/jmeiracorbal/mnemo/main/install.sh | bash -s -- --agent=windsurf
curl -sSf https://raw.githubusercontent.com/jmeiracorbal/mnemo/main/install.sh | bash -s -- --agent=codex

This installs hook scripts to the agent's global directory and registers the MCP server. Hooks are wired up once here, but they will do nothing in projects without a .mnemo marker.

Phase 2 — enable per project (once per project):

Run from the project root:

mnemo init --agent=claudecode   # or cursor, windsurf, codex, all

This creates a .mnemo marker, writes the agent protocol file, and configures per-project hook settings where the agent supports it. From this point on, hooks will fire when working in this project.

Agent capabilities

Not all agents support per-project hook configuration. The table below shows what each phase can configure per agent.

	Claude Code	Cursor	Windsurf	Codex
Hook scripts (global)	via plugin	~/.cursor/hooks/	~/.codeium/windsurf/hooks/	~/.codex/hooks/
MCP (always global)	~/.claude/.mcp.json	~/.cursor/mcp.json	~/.codeium/windsurf/mcp_config.json	~/.codex/config.toml
Per-project hook config	.claude/settings.json	.cursor/hooks.json	.windsurf/hooks.json	❌ global only
Per-project protocol	AGENTS.md + CLAUDE.md symlink	.cursor/rules/mnemo.mdc	.windsurf/rules/mnemo.md	AGENTS.md

Codex does not support per-project hook configuration. Its hooks are registered globally in ~/.codex/hooks.json and check for .mnemo at runtime before acting.

What mnemo init creates per agent

Claude Code