OMEGA

Persistent memory for AI coding agents. Your agent remembers decisions, learns from mistakes, and picks up where it left off.

🇨🇳 中文 | 🇯🇵 日本語 | 🇰🇷 한국어 | 🇧🇷 Português | 🇪🇸 Español | 🇫🇷 Français | 🇩🇪 Deutsch | 🇷🇺 Русский

pip3 install omega-memory[server]
omega setup

Works with Claude Code | Cursor | Windsurf | Zed | any MCP client

Why Not Just Use CLAUDE.md?

Claude Code's built-in CLAUDE.md is a flat markdown file. It works for a few notes. It breaks down when:

• You can't search it. 200 lines in, you're grepping for context that may or may not be there. OMEGA uses semantic search (bge-small-en-v1.5 embeddings + sqlite-vec) to find relevant memories even when the wording is different.
• It doesn't auto-capture. Every lesson has to be manually written. OMEGA detects decisions and debugging outcomes automatically.
• It grows forever. No dedup, no decay, no contradiction detection. OMEGA auto-resolves conflicts, deduplicates semantically similar entries, and decays stale memories over time.
• It's one file per project. No cross-project learning. OMEGA's memory graph spans your entire development history.
• It can't checkpoint. Stop mid-refactor and there's no way to resume. OMEGA saves task state and picks up exactly where you left off.

CLAUDE.md is fine for "always use tabs." OMEGA is for when your agent needs to actually learn.

Quick Start

pip3 install omega-memory[server]   # install from PyPI (includes MCP server)
omega setup                         # auto-configures Claude Code + hooks
omega doctor                        # verify everything works

Important: omega setup downloads the embedding model and configures your editor. Don't skip it.

That's it. Start a new Claude Code session and say "Remember that we always use early returns and never nest more than 2 levels." Close the session. Open a new one and ask "What are my code style preferences?" OMEGA recalls it instantly.

Using another editor? Install with pip3 install omega-memory[server], then:

omega setup --client cursor          # writes ~/.cursor/mcp.json
omega setup --client windsurf        # writes ~/.codeium/windsurf/mcp_config.json
omega setup --client zed             # writes ~/.config/zed/settings.json

{
  "mcpServers": {
    "omega-memory": {
      "command": "python3",
      "args": ["-m", "omega.server.mcp_server"]
    }
  }
}

pipx install omega-memory[server]              # recommended for global install (no venv needed)
pip3 install omega-memory[server]              # standard (may need a venv)
python3 -m pip install omega-memory[server]    # if pip3 is not available

pip3 install omega-memory    # core only, no MCP server process

from omega import store, query, remember

store("Always use TypeScript strict mode", "user_preference")
results = query("TypeScript preferences")

omega setup --hooks-only    # auto-capture + memory surfacing, no MCP server (~600MB RAM saved)

What It Does

After omega setup, OMEGA works in the background. No commands to learn.

Auto-capture -- When you make a decision or debug an issue, OMEGA detects it and stores it automatically.

Auto-surface -- When you edit a file or start a session, OMEGA surfaces relevant memories from past sessions.

Checkpoint & resume -- Stop mid-task, pick up in a new session exactly where you left off.

You can also explicitly tell Claude to remember things:

"Remember that we use JWT tokens, not session cookies"

But the real value is what OMEGA does without being asked.

Examples

Architectural decisions carry forward:

"Remember: we chose PostgreSQL over MongoDB for the orders service because we need ACID transactions for payment processing."

Three weeks later, in a new session:

"I'm adding a caching layer to the orders service -- what should I know?"

OMEGA surfaces the PostgreSQL decision automatically, so Claude doesn't suggest a MongoDB-style approach.

Mistakes become lessons:

You spend 30 minutes debugging a Docker build failure. Claude figures it out:

"The node_modules volume mount was shadowing the container's node_modules. Fixed by adding an anonymous volume."

OMEGA auto-captures this as a lesson. Next time anyone hits the same Docker issue, Claude already knows the fix.

Preferences persist:

"Remember: always use early returns. Never nest conditionals more than 2 levels deep. Prefer const over let."

Every future session follows these rules without being told again.

Tasks survive session boundaries:

You're mid-refactor when you need to stop:

"Checkpoint this -- I'm halfway through migrating the auth middleware to the new pattern."

Next session:

"Resume the auth middleware task."

Claude picks up exactly where you left off.

More examples (CLI, Python API, scripting): docs/examples

How It Compares

Full comparison at omegamax.co/compare.

Free vs Pro

OMEGA follows an open-core model. The free Core tier is Apache-2.0 licensed and will never be relicensed.

Core is complete. Most individual developers will never need Pro. Pro unlocks multi-agent coordination and enterprise capabilities for teams running multiple concurrent agents.

Benchmark

#1 on LongMemEval (ICLR 2025) -- the academic benchmark for long-term memory systems. 500 questions testing extraction, reasoning, temporal understanding, and preference tracking.

Details and methodology at omegamax.co/benchmarks.

Key Features

• 12 MCP Tools -- Store, query, traverse, checkpoint, resume, compact, consolidate, and more. Full tool reference at omegamax.co/docs.
• Semantic Search -- bge-small-en-v1.5 embeddings + sqlite-vec for fast, accurate retrieval.
• Auto-Capture & Surfacing -- Hooks automatically detect decisions and lessons, and surface relevant memories during work.
• Graph Relationships -- Memories linked with typed edges (related, supersedes, contradicts).
• Forgetting Intelligence -- Time decay, conflict resolution, deduplication. Preferences and errors are exempt from decay.
• Encryption at Rest (optional) -- AES-256-GCM with macOS Keychain integration. pip install omega-memory[encrypt]
• Plugin Architecture -- Extensible via entry points.

Compatibility

Supported Editors

Auto-capture hooks are currently only supported by Claude Code's hook system. All MCP-compatible clients get the full 12-tool memory API.

Python & OS

System Requirements

Who Uses OMEGA

OMEGA is used by developers running Claude Code, Cursor, and Windsurf who need persistent memory across sessions. From solo developers to teams running multi-agent workflows.

"I installed OMEGA and forgot about it. Two weeks later I realized my Claude sessions just... knew things from previous sessions."

If you're using OMEGA, open a PR to add yourself here.

Remote / SSH Setup

Run your agent on a remote server, SSH in from any device. OMEGA's memory graph is on the server waiting for you.

# On your remote server (any Linux VPS -- no GPU needed)
pip3 install omega-memory[server]
omega setup
omega doctor

Every SSH session has full memory of every previous session on that server. Survives disconnects. ~337 MB RAM after first query. Zero external services.

# In PowerShell (admin)
wsl --install

# In your WSL terminal
sudo apt update && sudo apt install -y python3 python3-pip python3-venv
python3 --version   # should be 3.11+

sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt update && sudo apt install -y python3.12 python3.12-venv

pip3 install omega-memory[server]
omega setup
omega doctor

               +---------------------+
               |    Claude Code       |
               |  (or any MCP host)   |
               +----------+----------+
                          | stdio/MCP
               +----------v----------+
               |   OMEGA MCP Server   |
               |   12 memory tools    |
               +----------+----------+
                          |
               +----------v----------+
               |    omega.db (SQLite) |
               | memories | edges |   |
               |     embeddings       |
               +----------------------+

git clone https://github.com/omega-memory/omega-memory.git
cd omega-memory
pip3 install -e ".[server,dev]"
omega setup

Troubleshooting

omega doctor shows FAIL on import:

• Ensure pip3 install -e ".[server]" from the repo root
• Check python3 -c "import omega" works

MCP server fails to start:

• Run pip3 install omega-memory[server] (the [server] extra includes the MCP package)

MCP server not registered:

claude mcp add omega-memory -- python3 -m omega.server.mcp_server

Hooks not firing:

• Check ~/.claude/settings.json has OMEGA hook entries
• Check ~/.omega/hooks.log for errors

Development

pip3 install -e ".[server,dev]"
pytest tests/
ruff check src/

Uninstall

claude mcp remove omega-memory
rm -rf ~/.omega ~/.cache/omega
pip3 uninstall omega-memory

Manually remove OMEGA entries from ~/.claude/settings.json and the <!-- OMEGA:BEGIN --> block from ~/.claude/CLAUDE.md.

Contributing

• Contributing Guide
• Security Policy
• Changelog
• Report a Bug

Star History

License

Apache-2.0. See LICENSE for details. The free Core tier is Apache-2.0 licensed and will never be relicensed.