io.github.omega-memory/core MCP Server

OMEGA

Cross-model memory for AI agents. Local-first. Works with Claude, GPT, Gemini, Cursor, Claw Code, and any MCP client. Your agent's brain shouldn't live on someone else's server, or be locked to one provider.

---

The Problem

AI coding agents are stateless. Every new session starts from zero. The "solutions" either lock you into one model provider or send your codebase context to their cloud.

• 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.
• Cloud memory = someone else's database. Services like Mem0 require API keys and send your data to their servers. When they change pricing, get acquired, or go down, your agent's accumulated intelligence disappears.
• Vendor lock-in. Anthropic's Memory Tool only works with Claude. OpenAI's memory only works with GPT. Switch models, lose your memory.

OMEGA solves this. Memory, coordination, and learning that runs entirely on your machine. Works with every major LLM and coding agent. No cloud. No API keys. No vendor lock-in.

<!-- TODO: terminal GIF showing memory recall across sessions --> <!-- mcp-name: io.github.omega-memory/omega-memory -->

Quick Install

pip install omega-memory[server]    # Full install (memory + MCP server)
omega setup                         # Downloads model, registers MCP, installs hooks
omega doctor                        # Verify everything works

Claude Desktop

pip install omega-memory[server]
omega setup --client claude-desktop

This registers OMEGA as an MCP server in Claude Desktop's config. Restart Claude Desktop to activate.

Cursor, Claw Code, Windsurf, Cline, Codex

pip install omega-memory[server]
omega setup --client cursor      # or: claw-code, windsurf, cline, codex

<details> <summary><strong>Library-only install (no MCP server)</strong></summary>

If you only need OMEGA as a Python library for scripts, CI/CD, or automation:

pip 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")

This gives you the full storage and retrieval API without running an MCP server (~50 MB lighter, no background process). Hooks still work:

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

</details>

From Source

git clone https://github.com/omega-memory/omega.git
cd omega
pip install -e ".[server,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 (Claude Code auto-detected, or specify --client)
4. Install session hooks into ~/.claude/settings.json
5. Add an OMEGA block to ~/.claude/CLAUDE.md

60-Second Quickstart

OMEGA works through natural language — no API calls, no configuration. Just talk to Claude.

1. Tell Claude to remember something:

"Remember that the auth system uses JWT tokens, not session cookies"

Claude stores this as a permanent memory with semantic embeddings.

2. Close the session. Open a new one.

3. Ask about it:

"What did I decide about authentication?"

OMEGA surfaces the relevant memory automatically:

Found 1 relevant memory:
  [decision] "The auth system uses JWT tokens, not session cookies"
  Stored 2 days ago | accessed 3 times

That's it. Memories persist across sessions, accumulate over time, and are surfaced automatically when relevant — even if you don't explicitly ask.

Key Features

• Memory & Learning — Stores decisions, lessons, error patterns, and preferences with semantic search. Claude recalls what matters without you re-explaining everything each session. 25 memory tools including compaction, consolidation, timeline, graph traversal, and context virtualization (checkpoint/resume).

• Multi-Agent Coordination (omega-pro) — File and branch locking, session management, task queues with dependencies, intent broadcasting, and agent-to-agent messaging. 29 coordination tools that prevent agents from overwriting each other's work.

• Intelligent LLM Routing (omega-pro) — Classifies tasks and routes to the optimal model. Coding → Claude Sonnet. Quick edit → Llama 8b at 1/60th the cost. 1M token context → Gemini Flash. 5 providers, 4 priority modes, sub-2ms intent classification.

• Knowledge Base (omega-pro) — Ingest PDFs, markdown, web pages, and text files into a searchable knowledge base with semantic chunking.

• Entity Registry (omega-pro) — Multi-entity corporate memory with relationships, hierarchies, and entity-scoped memories/profiles/documents.

• Secure Profile (omega-pro) — AES-256 encrypted personal data storage with macOS Keychain integration.

How OMEGA Compares

Feature	OMEGA	Anthropic Memory	Mem0	Zep
Works with any LLM/agent	Yes	Claude only	Yes	Yes
Your data stays on your machine	Yes	Partial*	No	No
No cloud dependency	Yes	No (needs API)	No	No
Semantic search + knowledge graph	Yes	No (file CRUD)	$249/mo	Yes
Multi-agent coordination	Yes (pro)	Research preview	No	No
Works with Claude Code, Cursor, Claw Code	Yes	Claude only	Partial	No
Free & open source	Yes (Apache 2.0)	No	Freemium	Freemium

Anthropic's Memory Tool stores data client-side but requires Claude API calls for all memory operations. OMEGA runs entirely on-device, including embeddings (ONNX).

Anthropic Memory is for Anthropic. OMEGA is for everyone.

Architecture

     Claude Code  ·  Cursor  ·  Claw Code  ·  Any MCP Client
               │         │         │              │
               └─────────┴─────┬───┴──────────────┘
                               │ stdio/MCP
               ┌───────────────▼─────────────┐
               │   OMEGA MCP Server   │
               │   25 core tools      │
               └──┬──────────────────┘
                  │
         ┌────────▼──────────────┐
         │ Core Memory Engine    │
         │ (semantic search,     │
         │  embeddings, graphs)  │
         └─────┬─────────────────┘
               │
               ▼
         ┌──────────────────────────────────────┐
         │         omega.db (SQLite)             │
         │  memories | edges | embeddings        │
         └──────────────────────────────────────┘

Single database, modular handlers. Optional modules (coordination, router, entity, knowledge, profile) are available via omega-pro and register into the same server process. No separate daemons, no microservices.

MCP Tools Reference

OMEGA runs as an MCP server inside Claude Code. The core package provides 25 memory tools. omega-pro adds coordination, routing, entity, knowledge, and profile tools.

Memory (25 tools)

Tool	What it does
omega_store	Store typed memory (decision, lesson, error, summary)
omega_query	Semantic search with tag filters and contextual re-ranking
omega_welcome	Session briefing with recent memories and profile
omega_profile	Read or update user profile
omega_delete_memory	Delete a specific memory by ID
omega_edit_memory	Edit the content of a memory
omega_list_preferences	List all stored user preferences
omega_health	Detailed health check with memory usage and recommendations
omega_backup	Export or import memories for backup/restore
omega_lessons	Cross-session lessons ranked by access count
omega_feedback	Record feedback on a surfaced memory
omega_clear_session	Clear all memories for a specific session
omega_similar	Find memories similar to a given one
omega_timeline	Memories grouped by day
omega_consolidate	Prune stale memories, cap summaries, clean edges
omega_traverse	Walk the relationship graph
omega_compact	Cluster and summarize related memories
omega_checkpoint	Save task state for cross-session continuity
omega_resume_task	Resume a previously checkpointed task
omega_remind	Set a time-based reminder
omega_remind_list	List active reminders
omega_remind_dismiss	Dismiss a reminder
omega_type_stats	Memory counts grouped by event type
omega_session_stats	Memory counts grouped by session
omega_weekly_digest	Weekly knowledge digest with stats and trends

Additional tools with omega-pro

Module	Tools	Description
Coordination	29	File/branch locking, sessions, tasks, messaging, audit
Router	10	LLM routing, intent classification, model switching
Entity	8	Corporate entities, relationships, hierarchies
Knowledge	5	Document ingestion, semantic search, RAG
Profile	3	AES-256 encrypted personal data storage

CLI

Command	Description
omega setup	Create dirs, download model, register MCP, install hooks (--hooks-only to skip MCP)
omega doctor	Verify installation health
omega status	Memory count, store size, model status
omega query <text>	Search memories by semantic similarity
omega store <text>	Store a memory with a specified type
omega timeline	Show memory timeline grouped by day
omega activity	Show recent session activity overview
omega stats	Memory type distribution and health summary
omega consolidate	Deduplicate, prune, and optimize memory
omega compact	Cluster and summarize related memories
omega backup	Back up omega.db (keeps last 5)
omega validate	Validate database integrity
omega logs	Show recent hook errors
omega migrate-db	Migrate legacy JSON to SQLite

<details> <summary><strong>Advanced Details</strong></summary>

Hooks (7 processes, 11 handlers)

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

Hook	Matcher	Handlers	Purpose
SessionStart	all	session_start	Welcome briefing, session resume
Stop	all	session_stop	Summary
UserPromptSubmit	all	auto_capture	Auto-capture lessons/decisions
PostToolUse	Edit/Write/NotebookEdit	surface_memories	Surface relevant memories
PostToolUse	Bash/Read	surface_memories	Surface relevant memories

With omega-pro, additional coordination handlers register automatically: session lifecycle, file/branch claim guards, heartbeat, and git push guards.

Storage

Path	Purpose
~/.omega/omega.db	SQLite database (memories, embeddings, edges)
~/.omega/profile.json	User profile
~/.omega/hooks.log	Hook error log
~/.cache/omega/models/bge-small-en-v1.5-onnx/	ONNX embedding model

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

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

Memory Footprint

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

What Gets Modified

omega setup modifies these files outside ~/.omega/:

• ~/.claude.json — Adds omega-memory MCP server entry
• ~/.claude/settings.json — Adds hook entries
• ~/.claude/CLAUDE.md — Adds a managed <!-- OMEGA:BEGIN --> block

All changes are idempotent.

</details>

Troubleshooting

omega doctor shows FAIL on import:

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

MCP server fails to start:

• Run pip 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

pip install -e ".[server,dev]"
pytest tests/                # 2198+ 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.