OMEGA

OMEGA

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

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

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.

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

Architecture

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

Single database, modular handlers. Additional tools available via the plugin system.

MCP Tools Reference

25 memory tools are available as an MCP server. Additional tools can be added via plugins.

Plus 11 more tools for health checks, backup/restore, stats, editing, and deletion. See tool_schemas.py for the full list.

CLI

Hooks

All hooks dispatch via fast_hook.py → daemon UDS socket, with fail-open semantics.

Storage

Search Pipeline

1. Vector similarity via sqlite-vec (cosine distance, 384-dim bge-small-en-v1.5)
2. Full-text search via FTS5 (fast keyword matching)
3. Type-weighted scoring (decisions/lessons weighted 2x)
4. Contextual re-ranking (boosts by tag, project, and content match)
5. Deduplication at query time
6. Time-decay weighting (old unaccessed memories rank lower)

Memory Lifecycle

• Dedup: SHA256 hash (exact) + embedding similarity 0.85+ (semantic) + Jaccard per-type
• Evolution: Similar content (55-95%) appends new insights to existing memories
• TTL: Session summaries expire after 1 day, lessons/preferences are permanent
• Auto-relate: Creates related edges (similarity >= 0.45) to top-3 similar memories
• Compaction: Clusters and summarizes related memories
• Decay: Unaccessed memories lose ranking weight over time (floor 0.35); preferences and errors exempt
• Conflict detection: Contradicting memories auto-detected on store; decisions auto-resolve, lessons flagged

Memory Footprint

• Startup: ~31 MB RSS
• After first query (ONNX model loaded): ~337 MB RSS
• Database: ~10.5 MB for ~242 memories

Install from Source

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

omega setup will:

1. Create ~/.omega/ directory
2. Download the ONNX embedding model (~90 MB) to ~/.cache/omega/models/
3. Register omega-memory as an MCP server in ~/.claude.json
4. Install session hooks in ~/.claude/settings.json
5. Add a managed <!-- OMEGA:BEGIN --> block to ~/.claude/CLAUDE.md

All changes are idempotent — running omega setup again won't duplicate entries.

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.