OMEGA

The memory system for AI coding agents. Decisions, lessons, and context that persist across sessions.

mcp-name: io.github.omega-memory/omega-memory

The Problem

AI coding agents are stateless. Every new session starts from zero.

• Context loss. Agents forget every decision, preference, and architectural choice between sessions. Developers spend 10-30 minutes per session re-explaining context that was already established.
• Repeated mistakes. Without learning from past sessions, agents make the same errors over and over. They don't remember what worked, what failed, or why a particular approach was chosen.

OMEGA gives AI coding agents long-term memory and cross-session learning, all running locally on your machine.

Quick Start

pip install omega-memory    # install from PyPI
omega setup                 # auto-configures Claude Code + hooks
omega doctor                # verify everything works

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.

Full architecture walkthrough and setup guide: omegamax.co/quickstart

Using Cursor, Windsurf, or Zed?

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

What Happens Next

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 — even ones you forgot about.

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

"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.

Learning from Mistakes

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.

Code Preferences

"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.

Task Continuity

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 — files changed, decisions made, what's left to do.

Error Patterns

Claude encounters the same ECONNRESET three sessions in a row. Each time OMEGA surfaces the previous fix:

[error_pattern] ECONNRESET on API calls — caused by connection pool exhaustion.
Fix: set maxSockets to 50 in the http agent config.
Accessed 3 times

No more re-debugging the same issue.

Key Features

• Auto-Capture & Surfacing — Hook system automatically captures decisions and lessons, and surfaces relevant memories before edits, at session start, and during work.

• Persistent Memory — Stores decisions, lessons, error patterns, and preferences with semantic search. Your agent recalls what matters without you re-explaining everything each session.

• Semantic Search — bge-small-en-v1.5 embeddings + sqlite-vec for fast, accurate retrieval. Finds relevant memories even when the wording is different.

• Cross-Session Learning — Lessons, preferences, and error patterns accumulate over time. Agents learn from past mistakes and build on previous decisions.

• Forgetting Intelligence — Memories decay naturally over time, conflicts auto-resolve, and every deletion is audited. Preferences and error patterns are exempt from decay.

• Graph Relationships — Memories are linked with typed edges (related, supersedes, contradicts). Traverse the knowledge graph to find connected context.

• Encryption at Rest (optional) — AES-256-GCM encrypted storage with macOS Keychain integration. pip install omega-memory[encrypt]

• Plugin Architecture — Extensible via entry points. Add custom tools and handlers through the plugin system.

How OMEGA Compares

MEMORY.md is Claude Code's built-in markdown file -- great for simple notes, but no search, no auto-capture, and it grows unbounded. Mem0 offers strong semantic memory but requires cloud API keys and has no checkpoint/resume or contradiction detection. Basic MCP memory servers (e.g., simple key-value stores) provide persistence but lack the intelligence layer -- no semantic search, no forgetting, no graph.

OMEGA gives you the best of all worlds: fully local, zero cloud dependencies, with intelligent features that go far beyond simple storage.

Full comparison with methodology at omegamax.co/compare.

Benchmark

OMEGA scores 95.4% task-averaged on LongMemEval (ICLR 2025), an academic benchmark that tests long-term memory across 5 categories: information extraction, multi-session reasoning, temporal reasoning, knowledge updates, and preference tracking. Raw accuracy is 466/500 (93.2%). Task-averaged scoring (mean of per-category accuracies) is the standard methodology used by other systems on the leaderboard. This is the #1 score on the leaderboard.

Details and methodology at omegamax.co/benchmarks.

Compatibility

All clients get full access to all 12 core memory tools. Auto-capture hooks (automatic memory surfacing and context capture) require Claude Code.

Requires Python 3.11+. macOS and Linux supported. Windows via WSL.

Remote / SSH Setup

Claude Code's SSH support lets you run your agent on a remote server from any device. OMEGA makes that server remember everything across sessions and reconnections.

# On your remote server (any Linux VPS — no GPU needed)
pip install omega-memory
omega setup
omega doctor

That's it. Every SSH session — from your laptop, phone, or tablet — now has full memory of every previous session on that server.

Why this matters:

• Device-agnostic memory — SSH in from any device, OMEGA's memory graph is on the server waiting for you
• Survives disconnects — SSH drops? Reconnect and omega_resume_task picks up exactly where you left off
• Always-on accumulation — A cloud VM running 24/7 means your memory graph grows continuously
• Team-ready — Multiple developers SSH to the same server? OMEGA tracks who's working on what with file claims, handoff notes, and peer messaging

Requirements: Any VPS with Python 3.11+ (~337 MB RAM after first query). SQLite + CPU-only ONNX embeddings — zero external services.

               ┌─────────────────────┐
               │    Claude Code       │
               │  (or any MCP host)   │
               └──────────┬──────────┘
                          │ stdio/MCP
               ┌──────────▼──────────┐
               │   OMEGA MCP Server   │
               │   12 memory tools    │
               └──────────┬──────────┘
                          │
               ┌──────────▼──────────┐
               │    omega.db (SQLite) │
               │ memories | edges |   │
               │     embeddings       │
               └──────────────────────┘

git clone https://github.com/omega-memory/omega-memory.git
cd core
pip install -e ".[dev]"
omega setup

Troubleshooting

omega doctor shows FAIL on import:

• Ensure pip install -e . from the repo root
• Check python3 -c "import omega" works

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

pip install -e ".[dev]"
pytest tests/
ruff check src/              # Lint

Uninstall

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

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

Star History

Contributing

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

License

Apache-2.0 — see LICENSE for details.