OMEGA

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

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 Install

pip install omega-memory
omega setup
omega doctor

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

Compatibility

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

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

git clone https://github.com/omega-memory/core.git
cd omega
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.

Contributing

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

License

Apache-2.0 — see LICENSE for details.