Persistent memory that any AI agent can read and write. Quit Claude Code mid-task, open Codex in the same directory — it picks up where you left off.

📚 Full documentation lives in openwiki/ — start with the quickstart and follow the links for architecture, workflows, integrations, and testing.

Features

• Scoped memory — session → context (branch) → project → global, resolved automatically from cwd
• Cross-agent handoffs — typed records with summary, open questions, next steps
• Semantic search — spaCy + sqlite-vec + BM25/FTS5/hybrid RRF fusion
• Lifecycle hooks — fire-and-forget HTTP endpoint, payload sanitization, immutable observations
• Zero LLM tokens for writes — bulk writes (conversation archiving, logging) via hooks only
• Retention — salience-based decay with tiers (working/procedural/semantic), pin/unpin
• Auth — Bearer token, host allowlisting, CORS
• Web UI — dark mode viewer (dashboard, projects, search, audit log) with edit, pin/unpin, trash/restore, import/export, and batch actions
• Backup/restore — tarball CLI commands
• Multi-agent — Claude Code, OpenCode, Codex, Cursor, Gemini CLI, VS Code, Docker

Prerequisites

mymem0ry doctor checks all prerequisites and auto-downloads the spaCy language model if missing.

Install

uv tool install mymem0ry
mymem0ry doctor

The default spaCy model is English (en_core_web_lg). For Portuguese, set SPACY_MODEL=pt_core_news_lg in .env before running mymem0ry doctor.

Zero config: after install, just add the MCP server + hooks to your agent config below. The HTTP server auto-starts when the MCP server runs — no separate serve command needed.

Agent Setup

Claude Code

claude mcp add --scope user mymem0ry -- mymem0ry-mcp

MCP + hooks in ~/.claude/settings.json:

First get the correct hooks paths:

mymem0ry hooks --config

Then copy the printed snippet into your settings.json. Example result:

{
  "mcpServers": {
    "mymem0ry": {
      "type": "stdio",
      "command": "mymem0ry-mcp"
    }
  },
  "hooks": {
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [{"type": "command", "command": "/home/user/.local/share/mymem0ry/hooks/claude-code/session-start.sh"}]
      }
    ],
    "SessionEnd": [
      {
        "matcher": "",
        "hooks": [{"type": "command", "command": "/home/user/.local/share/mymem0ry/hooks/claude-code/session-end.sh"}]
      }
    ]
  }
}

OpenCode

Add to ~/.config/opencode/opencode.json (global) or ./opencode.json (project):

{
  "mcp": {
    "mymem0ry": {
      "type": "local",
      "command": ["mymem0ry-mcp"],
      "timeout": 30000,
      "enabled": true
    }
  }
}

Note: timeout: 30000 (30s) is recommended because loading the spaCy model on first run can exceed the default 5s timeout.

If mymem0ry-mcp is not on PATH (e.g. installed via uv sync in a project), use the full path:

{
  "mcp": {
    "mymem0ry": {
      "type": "local",
      "command": ["uv", "run", "--directory", "/path/to/myMem0ry", "mymem0ry-mcp"],
      "timeout": 30000,
      "enabled": true
    }
  }
}

Codex CLI

codex mcp add mymem0ry -- mymem0ry-mcp

VS Code

code --add-mcp '{"name":"mymem0ry","command":"mymem0ry-mcp"}'

Cursor

cursor --add-mcp '{"name":"mymem0ry","command":"mymem0ry-mcp"}'

Gemini CLI

Same stdio pattern. Add to Gemini CLI MCP config with command: mymem0ry-mcp.

Docker

docker compose -f docker/docker-compose.yml up -d
curl http://127.0.0.1:49374/health

For detailed per-agent instructions: docs/install.md

Using with Code Intelligence Tools

myMem0ry focuses on curated, human memory: decisions, facts, patterns, handoffs and conversations. It pairs well with code-intelligence MCP servers that understand the codebase itself.

Recommended division of labour:

The system prompt exposed by myMem0ry instructs the agent to prefer Serena for symbol-level work and codebase-memory-mcp for structural analysis, while routing decisions and long-lived context through myMem0ry.

Lifecycle Hooks

Hooks POST lifecycle events to POST /hook on the myMem0ry HTTP server. The server auto-starts when the MCP server runs — no manual serve step needed.

Hook payload fields:

All payloads are sanitized: secrets redacted, home paths stripped, fields truncated.

Configuration

All via environment variables (or .env file in the project root):

# Custom storage location
export DB_PATH=/path/to/shared/memories.db
export CONVERSATIONS_DIR=/path/to/shared/conversations

# Portuguese language support
export SPACY_MODEL=pt_core_news_lg
mymem0ry doctor

Cross-machine sync

Keep data/ in a git repository and enable auto-sync to synchronize memories across machines.

Setup

# 1. Initialize a git repository for the data directory
cd data
git init
git remote add origin https://github.com/you/my-mem0ry-data.git
cat > .gitignore <<'EOF'
*.pid
spool/
EOF
git add .
git commit -m "initial memory data"
git push -u origin main

# 2. Enable auto-sync
export MEM0RY_GIT_AUTO_SYNC=1

With auto-sync enabled, myMem0ry pulls before reads and pushes after memory writes.

Sync commands

mymem0ry git-sync status        # show repository status
mymem0ry git-sync pull          # pull latest changes
mymem0ry git-sync push          # commit and push local changes

On a new machine

git clone https://github.com/you/my-mem0ry-data.git data
mymem0ry index --backend vector

Conflict resolution

Git auto-sync is last-write-wins and designed for single-user workflows. If a conflict occurs, resolve it manually:

cd data
git add .
git rebase --continue
mymem0ry git-sync push

See docs/sync.md for more details and alternatives.

Import Conversations

myMem0ry auto-detects the format. Supports ChatGPT, Gemini, and Claude exports.

mymem0ry split                                    # Auto-detect
mymem0ry split --source path/to/chatgpt-export    # Specific source
mymem0ry split --source path/to/data --type claude-code  # Force parser

mymem0ry index                                    # Build indexes
mymem0ry migrate                                  # Migrate to structured memory

CLI Commands

# Context & search
mymem0ry context --cwd .                          # Load context for current project
mymem0ry save "Title" "Content" --scope project   # Save a memory
mymem0ry log "message"                            # Quick session log
mymem0ry search "query"                           # ripgrep search
mymem0ry search "query" --backend hybrid --expand # BM25+vector RRF fusion

# Overview
mymem0ry stats                                    # Database overview
mymem0ry projects                                 # List projects with memories
mymem0ry doctor                                   # System health check

# Retention
mymem0ry decay --days 90 --dry-run                # Preview decay
mymem0ry pin <memory_id>                          # Pin memory (exempt from decay)
mymem0ry unpin <memory_id>
mymem0ry forget-sweep --dry-run                   # Preview salience-based sweep

# Handoffs
mymem0ry handoff begin --summary "..."            # Create handoff for next agent
mymem0ry handoff accept                           # Accept pending handoff
mymem0ry handoff status                           # Check server status

# Hooks
mymem0ry hooks --config                       # Print settings.json snippet
mymem0ry hooks --path                         # Print hooks directory path
mymem0ry hooks --install                      # Install hooks for detected agent

# Server & backup
mymem0ry serve                                    # Start HTTP server
mymem0ry serve --detach                           # Start in background
mymem0ry backup --to backup.tar.gz                # Backup DB + conversations
mymem0ry restore --from backup.tar.gz             # Restore from backup

Memory Scopes

Resolved automatically from cwd — no manual configuration needed:

get_context() aggregates all 4 levels in priority order.

Retention & Pinning

Memories decay based on their type:

Pinning exempts a memory from decay — pinned memories are never deleted by forget-sweep. Use memory_pin / memory_unpin (or CLI mymem0ry pin / mymem0ry unpin) to protect important memories.

Fact evolution (evolve_fact) consolidates contradictory facts. When information changes (e.g. "Uses Postgres" → "Migrated to SQLite"), the old fact is soft-deleted and a new evolved fact replaces it, keeping the memory clean and current.

MCP Tools + Hook Writes

MCP Tools (low token cost — reads + selective writes)

Hook writes (zero LLM tokens)

Web UI

When running in HTTP mode (MCP_TRANSPORT=streamable-http), a web UI is available:

• / — Dashboard with stats and recent memories
• /projects — List of projects with memory counts
• /project/{id} — Project detail with memories
• /memory/{id} — Single memory detail
• /search — Full-text search with scope/type filters
• /audit — Audit log of all mutations

Documentation

This repo keeps two documentation layers: user-facing guides in docs/ and the project OpenWiki in openwiki/ (the living reference for architecture, workflows, integrations, and testing).

OpenWiki (start here)

• openwiki/quickstart.md — One-minute setup, layout, env vars, and where to go next
• openwiki/architecture/overview.md — How CLI, MCP, DB, search, and web UI fit together
• openwiki/architecture/data-model.md — Schema v9, tables, FTS5, sqlite-vec, retention tiers
• openwiki/workflows/agent-setup.md — MCP transports, hooks, scoped memory, handoffs, git sync
• openwiki/workflows/operations.md — CLI commands: context, save, migrate, retention, backup, diagnostics
• openwiki/integrations/mcp-and-web.md — MCP tool reference, HTTP routes, auth/CORS
• openwiki/testing.md — Test organization, CI pipeline, and targeted test tips

User guides

• docs/install.md — Detailed per-agent install instructions
• docs/usage.md — Usage guide, hooks, and workflows
• docs/sync.md — Cross-machine git sync workflow
• AGENTS.md — Architecture and developer reference

Development

git clone https://github.com/cccadet/myMem0ry.git
cd myMem0ry
bin/setup
uv run python -m pytest
uv run ruff check .

License

MIT