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

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.

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

If you only need OMEGA as a Python library for scripts, CI/CD, or automation, you can skip the MCP server entirely:

This gives you the full storage and retrieval API without running an MCP server (~50 MB lighter, no background process). You won't get MCP tools in your editor, but hooks still work:

Using Cursor, Windsurf, or Zed? Install with pip3 install omega-memory[server], then:

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:

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.

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

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

MCP Tools Reference

12 core memory tools are available as an MCP server. Full tool reference at omegamax.co/docs.

Additional utility tools for health checks, backup/restore, stats, editing, and deletion are also available. See omegamax.co/docs for the full reference.

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

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

• 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:

Hooks not firing:

• Check ~/.claude/settings.json has OMEGA hook entries

• Check ~/.omega/hooks.log for errors

Development

Uninstall

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.