OMEGA

1# OMEGA
2 
3**The memory system for AI coding agents.** Decisions, lessons, and context that persist across sessions.
4 
5[![PyPI version](https://img.shields.io/pypi/v/omega-memory.svg)](https://pypi.org/project/omega-memory/)
6[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
7[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
8[![GitHub stars](https://img.shields.io/github/stars/omega-memory/omega-memory?style=social)](https://github.com/omega-memory/omega-memory)
9[![Tests](https://github.com/omega-memory/omega-memory/actions/workflows/test.yml/badge.svg)](https://github.com/omega-memory/omega-memory/actions/workflows/test.yml)
10[![#1 on LongMemEval](https://img.shields.io/badge/LongMemEval-95.4%25_%231_Overall-gold.svg)](https://omegamax.co/benchmarks)
11[![smithery badge](https://smithery.ai/badge/omegamemory/omega-memory)](https://smithery.ai/server/omegamemory/omega-memory)
12 
13mcp-name: io.github.omega-memory/omega-memory
14 
15## The Problem
16 
17AI coding agents are stateless. Every new session starts from zero.
18 
19- **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.
20- **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.
21 
22OMEGA gives AI coding agents long-term memory and cross-session learning, all running locally on your machine.
23 
24![OMEGA demo — cross-session memory recall](https://raw.githubusercontent.com/omega-memory/omega-memory/main/assets/demo.gif)
25 
26---
27 
28## Quick Start
29 
30```bash
31pip3 install omega-memory[server]   # install from PyPI (includes MCP server)
32omega setup                         # auto-configures Claude Code + hooks
33omega doctor                        # verify everything works
34```
35 
36> **Important:** `omega setup` downloads the embedding model and configures your editor. Don't skip it.
37 
38That'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.
39 
40**Full architecture walkthrough and setup guide:** [omegamax.co/quickstart](https://omegamax.co/quickstart)
41 
42<details>
43<summary><strong>Alternative install methods</strong></summary>
44 
45```bash
46pipx install omega-memory[server]              # recommended for global install (no venv needed)
47pip3 install omega-memory[server]              # standard (may need a venv)
48python3 -m pip install omega-memory[server]    # if pip3 is not available
49```
50 
51</details>
52 
53<details>
54<summary><strong>Library-only install (no MCP server)</strong></summary>
55 
56If you only need OMEGA as a Python library for scripts, CI/CD, or automation, you can skip the MCP server entirely:
57 
58```bash
59pip3 install omega-memory    # core only, no MCP server process
60```
61 
62```python
63from omega import store, query, remember
64 
65store("Always use TypeScript strict mode", "user_preference")
66results = query("TypeScript preferences")
67```
68 
69This 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:
70 
71```bash
72omega setup --hooks-only    # auto-capture + memory surfacing, no MCP server (~600MB RAM saved)
73```
74 
75</details>
76 
77**Using Cursor, Windsurf, or Zed?** Install with `pip3 install omega-memory[server]`, then:
78 
79```bash
80omega setup --client cursor          # writes ~/.cursor/mcp.json
81omega setup --client windsurf        # writes ~/.codeium/windsurf/mcp_config.json
82omega setup --client zed             # writes ~/.config/zed/settings.json
83```
84 
85## What Happens Next
86 
87After `omega setup`, OMEGA works in the background. No commands to learn.
88 
89**Auto-capture** — When you make a decision or debug an issue, OMEGA detects it and stores it automatically.
90 
91**Auto-surface** — When you edit a file or start a session, OMEGA surfaces relevant memories from past sessions — even ones you forgot about.
92 
93**Checkpoint & resume** — Stop mid-task, pick up in a new session exactly where you left off.
94 
95You can also explicitly tell Claude to remember things:
96 
97> "Remember that we use JWT tokens, not session cookies"
98 
99But the real value is what OMEGA does without being asked.
100 
101## Examples
102 
103### Architectural Decisions
104 
105> "Remember: we chose PostgreSQL over MongoDB for the orders service because we need ACID transactions for payment processing."
106 
107Three weeks later, in a new session:
108 
109> "I'm adding a caching layer to the orders service — what should I know?"
110 
111OMEGA surfaces the PostgreSQL decision automatically, so Claude doesn't suggest a MongoDB-style approach.
112 
113### Learning from Mistakes
114 
115You spend 30 minutes debugging a Docker build failure. Claude figures it out:
116 
117> *"The node_modules volume mount was shadowing the container's node_modules. Fixed by adding an anonymous volume."*
118 
119OMEGA auto-captures this as a lesson. Next time anyone hits the same Docker issue, Claude already knows the fix.
120 
121### Code Preferences
122 
123> "Remember: always use early returns. Never nest conditionals more than 2 levels deep. Prefer `const` over `let`."
124 
125Every future session follows these rules without being told again.
126 
127### Task Continuity
128 
129You're mid-refactor when you need to stop:
130 
131> "Checkpoint this — I'm halfway through migrating the auth middleware to the new pattern."
132 
133Next session:
134 
135> "Resume the auth middleware task."
136 
137Claude picks up exactly where you left off — files changed, decisions made, what's left to do.
138 
139### Error Patterns
140 
141Claude encounters the same `ECONNRESET` three sessions in a row. Each time OMEGA surfaces the previous fix:
142 
143```
144[error_pattern] ECONNRESET on API calls — caused by connection pool exhaustion.
145Fix: set maxSockets to 50 in the http agent config.
146Accessed 3 times
147```
148 
149No more re-debugging the same issue.
150 
151## Key Features
152 
153- **Auto-Capture & Surfacing** — Hook system automatically captures decisions and lessons, and surfaces relevant memories before edits, at session start, and during work.
154 
155- **Persistent Memory** — Stores decisions, lessons, error patterns, and preferences with semantic search. Your agent recalls what matters without you re-explaining everything each session.
156 
157- **Semantic Search** — bge-small-en-v1.5 embeddings + sqlite-vec for fast, accurate retrieval. Finds relevant memories even when the wording is different.
158 
159- **Cross-Session Learning** — Lessons, preferences, and error patterns accumulate over time. Agents learn from past mistakes and build on previous decisions.
160 
161- **Forgetting Intelligence** — Memories decay naturally over time, conflicts auto-resolve, and every deletion is audited. Preferences and error patterns are exempt from decay.
162 
163- **Graph Relationships** — Memories are linked with typed edges (related, supersedes, contradicts). Traverse the knowledge graph to find connected context.
164 
165- **Encryption at Rest** *(optional)* — AES-256-GCM encrypted storage with macOS Keychain integration. `pip install omega-memory[encrypt]`
166 
167- **Plugin Architecture** — Extensible via entry points. Add custom tools and handlers through the plugin system.
168 
169## How OMEGA Compares
170 
171| Feature | OMEGA | MEMORY.md | Mem0 | Basic MCP Memory |
172|---------|:-----:|:---------:|:----:|:----------------:|
173| Persistent across sessions | Yes | Yes | Yes | Yes |
174| Semantic search | Yes | No (file grep only) | Yes | Varies |
175| Auto-capture (no manual effort) | Yes | No (manual edits) | Yes (cloud) | No |
176| Contradiction detection | Yes | No | No | No |
177| Checkpoint & resume tasks | Yes | No | No | No |
178| Graph relationships | Yes | No | No | No |
179| Cross-session learning | Yes | Limited | Yes | No |
180| Intelligent forgetting | Yes | No (grows forever) | No | No |
181| Local-only (no cloud/API keys) | Yes | Yes | No (API key required) | Yes |
182| Setup complexity | `pip3 install` + `omega setup` | Zero (built-in) | API key + cloud config | Manual JSON config |
183 
184**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.
185 
186OMEGA gives you the best of all worlds: fully local, zero cloud dependencies, with intelligent features that go far beyond simple storage.
187 
188Full comparison with methodology at [omegamax.co/compare](https://omegamax.co/compare).
189 
190## Benchmark
191 
192OMEGA scores **95.4% task-averaged** on [LongMemEval](https://github.com/xiaowu0162/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**.
193 
194| System | Score | Notes |
195|--------|------:|-------|
196| **OMEGA** | **95.4%** | **#1** |
197| Mastra | 94.87% | #2 |
198| Emergence | 86.0% | — |
199| Zep/Graphiti | 71.2% | Published in their paper |
200 
201Details and methodology at [omegamax.co/benchmarks](https://omegamax.co/benchmarks).
202 
203## Compatibility
204 
205| Client | 12 MCP Tools | Auto-Capture Hooks | Setup Command |
206|--------|:------------:|:------------------:|---------------|
207| Claude Code | Yes | Yes | `omega setup` |
208| Cursor | Yes | No | `omega setup --client cursor` |
209| Windsurf | Yes | No | `omega setup --client windsurf` |
210| Zed | Yes | No | `omega setup --client zed` |
211| Any MCP Client | Yes | No | Manual config (see docs) |
212 
213All clients get full access to all 12 core memory tools. Auto-capture hooks (automatic memory surfacing and context capture) require Claude Code.
214 
215Requires Python 3.11+. macOS and Linux supported. Windows via WSL.
216 
217## Remote / SSH Setup
218 
219Claude 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.
220 
221```bash
222# On your remote server (any Linux VPS — no GPU needed)
223pip3 install omega-memory[server]
224omega setup
225omega doctor
226```
227 
228That's it. Every SSH session — from your laptop, phone, or tablet — now has full memory of every previous session on that server.
229 
230**Why this matters:**
231 
232- **Device-agnostic memory** — SSH in from any device, OMEGA's memory graph is on the server waiting for you
233- **Survives disconnects** — SSH drops? Reconnect and `omega_resume_task` picks up exactly where you left off
234- **Always-on accumulation** — A cloud VM running 24/7 means your memory graph grows continuously
235- **Team-ready** — Multiple developers SSH to the same server? OMEGA tracks who's working on what with file claims, handoff notes, and peer messaging
236 
237**Requirements:** Any VPS with Python 3.11+ (~337 MB RAM after first query). SQLite + CPU-only ONNX embeddings — zero external services.
238 
239## Windows (WSL) Setup
240 
241OMEGA runs on Windows through [WSL 2](https://learn.microsoft.com/en-us/windows/wsl/install) (Windows Subsystem for Linux). WSL 1 works but WSL 2 is recommended for better SQLite performance.
242 
243**1. Install WSL 2 (if you don't have it)**
244 
245```powershell
246# In PowerShell (admin)
247wsl --install
248```
249 
250This installs Ubuntu by default. Restart when prompted.
251 
252**2. Install Python 3.11+ inside WSL**
253 
254```bash
255# In your WSL terminal
256sudo apt update && sudo apt install -y python3 python3-pip python3-venv
257python3 --version   # should be 3.11+
258```
259 
260If your distro ships an older Python, use the deadsnakes PPA:
261 
262```bash
263sudo add-apt-repository ppa:deadsnakes/ppa
264sudo apt update && sudo apt install -y python3.12 python3.12-venv
265```
266 
267**3. Install and set up OMEGA**
268 
269```bash
270pip3 install omega-memory[server]
271omega setup
272omega doctor
273```
274 
275**WSL-specific gotchas:**
276 
277- **Use the Linux filesystem, not `/mnt/c/`.** OMEGA stores data in `~/.omega/` inside WSL. Keep your projects on the Linux side (`~/Projects/`) for best performance. Accessing files on `/mnt/c/` is significantly slower due to filesystem translation.
278- **Keyring may not work out of the box.** If you use `omega-memory[encrypt]`, the keyring backend needs configuration. Install `keyrings.alt` for a file-based backend: `pip3 install keyrings.alt`. Alternatively, set the environment variable `OMEGA_ENCRYPTION_KEY` directly.
279- **Claude Code runs inside WSL.** Install Claude Code in your WSL terminal, not in Windows PowerShell. Your `~/.claude/` config lives in the WSL filesystem.
280- **Model cache path.** The ONNX embedding model downloads to `~/.cache/omega/models/` inside WSL (~90 MB). This is separate from any Windows-side cache.
281- **Multiple WSL distros.** Each distro has its own `~/.omega/` directory. If you switch distros, your memories don't carry over. Copy `~/.omega/omega.db` to transfer them.
282 
283<details>
284<summary><strong>Architecture & Advanced Details</strong></summary>
285 
286### Architecture
287 
288```
289               ┌─────────────────────┐
290               │    Claude Code       │
291               │  (or any MCP host)   │
292               └──────────┬──────────┘
293                          │ stdio/MCP
294               ┌──────────▼──────────┐
295               │   OMEGA MCP Server   │
296               │   12 memory tools    │
297               └──────────┬──────────┘
298                          │
299               ┌──────────▼──────────┐
300               │    omega.db (SQLite) │
301               │ memories | edges |   │
302               │     embeddings       │
303               └──────────────────────┘
304```
305 
306Single database, modular handlers. Additional tools available via the plugin system.
307 
308### MCP Tools Reference
309 
31012 core memory tools are available as an MCP server. Full tool reference at [omegamax.co/docs](https://omegamax.co/docs).
311 
312| Tool | What it does |
313|------|-------------|
314| `omega_store` | Store typed memory (decision, lesson, error, preference, summary) |
315| `omega_query` | Semantic or phrase search with tag filters and contextual re-ranking |
316| `omega_lessons` | Cross-session lessons ranked by access count |
317| `omega_welcome` | Session briefing with recent memories and profile |
318| `omega_profile` | Read or update the user profile |
319| `omega_checkpoint` | Save task state for cross-session continuity |
320| `omega_resume_task` | Resume a previously checkpointed task |
321| `omega_similar` | Find memories similar to a given one |
322| `omega_traverse` | Walk the relationship graph |
323| `omega_compact` | Cluster and summarize related memories |
324| `omega_consolidate` | Prune stale memories, cap summaries, clean edges |
325| `omega_timeline` | Memories grouped by day |
326| `omega_remind` | Set time-based reminders |
327| `omega_feedback` | Rate surfaced memories (helpful, unhelpful, outdated) |
328 
329Additional utility tools for health checks, backup/restore, stats, editing, and deletion are also available. See [omegamax.co/docs](https://omegamax.co/docs) for the full reference.
330 
331### CLI
332 
333| Command | Description |
334|---------|-------------|
335| `omega setup` | Create dirs, download model, register MCP, install hooks (`--hooks-only` to skip MCP) |
336| `omega doctor` | Verify installation health |
337| `omega status` | Memory count, store size, model status |
338| `omega query <text>` | Search memories by semantic similarity |
339| `omega store <text>` | Store a memory with a specified type |
340| `omega timeline` | Show memory timeline grouped by day |
341| `omega activity` | Show recent session activity overview |
342| `omega stats` | Memory type distribution and health summary |
343| `omega consolidate` | Deduplicate, prune, and optimize memory |
344| `omega compact` | Cluster and summarize related memories |
345| `omega backup` | Back up omega.db (keeps last 5) |
346| `omega validate` | Validate database integrity |
347| `omega logs` | Show recent hook errors |
348| `omega migrate-db` | Migrate legacy JSON to SQLite |
349 
350### Hooks
351 
352All hooks dispatch via `fast_hook.py` → daemon UDS socket, with fail-open semantics.
353 
354| Hook | Handlers | Purpose |
355|------|----------|---------|
356| SessionStart | `session_start` | Welcome briefing with recent memories |
357| Stop | `session_stop` | Session summary |
358| UserPromptSubmit | `auto_capture` | Auto-capture lessons/decisions |
359| PostToolUse | `surface_memories` | Surface relevant memories during work |
360 
361### Storage
362 
363| Path | Purpose |
364|------|---------|
365| `~/.omega/omega.db` | SQLite database (memories, embeddings, edges) |
366| `~/.omega/profile.json` | User profile |
367| `~/.omega/hooks.log` | Hook error log |
368| `~/.cache/omega/models/bge-small-en-v1.5-onnx/` | ONNX embedding model |
369 
370### Search Pipeline
371 
3721. **Vector similarity** via sqlite-vec (cosine distance, 384-dim bge-small-en-v1.5)
3732. **Full-text search** via FTS5 (fast keyword matching)
3743. **Type-weighted scoring** (decisions/lessons weighted 2x)
3754. **Contextual re-ranking** (boosts by tag, project, and content match)
3765. **Deduplication** at query time
3776. **Time-decay weighting** (old unaccessed memories rank lower)
378 
379### Memory Lifecycle
380 
381- **Dedup**: SHA256 hash (exact) + embedding similarity 0.85+ (semantic) + Jaccard per-type
382- **Evolution**: Similar content (55-95%) appends new insights to existing memories
383- **TTL**: Session summaries expire after 1 day, lessons/preferences are permanent
384- **Auto-relate**: Creates `related` edges (similarity >= 0.45) to top-3 similar memories
385- **Compaction**: Clusters and summarizes related memories
386- **Decay**: Unaccessed memories lose ranking weight over time (floor 0.35); preferences and errors exempt
387- **Conflict detection**: Contradicting memories auto-detected on store; decisions auto-resolve, lessons flagged
388 
389### Memory Footprint
390 
391- Startup: ~31 MB RSS
392- After first query (ONNX model loaded): ~337 MB RSS
393- Database: ~10.5 MB for ~242 memories
394 
395### Install from Source
396 
397```bash
398git clone https://github.com/omega-memory/omega-memory.git
399cd omega-memory
400pip3 install -e ".[server,dev]"
401omega setup
402```
403 
404`omega setup` will:
4051. Create `~/.omega/` directory
4062. Download the ONNX embedding model (~90 MB) to `~/.cache/omega/models/`
4073. Register `omega-memory` as an MCP server in `~/.claude.json`
4084. Install session hooks in `~/.claude/settings.json`
4095. Add a managed `<!-- OMEGA:BEGIN -->` block to `~/.claude/CLAUDE.md`
410 
411All changes are idempotent — running `omega setup` again won't duplicate entries.
412 
413</details>
414 
415## Troubleshooting
416 
417**`omega doctor` shows FAIL on import:**
418- Ensure `pip3 install -e ".[server]"` from the repo root
419- Check `python3 -c "import omega"` works
420 
421**MCP server fails to start:**
422- Run `pip3 install omega-memory[server]` (the `[server]` extra includes the MCP package)
423 
424**MCP server not registered:**
425```bash
426claude mcp add omega-memory -- python3 -m omega.server.mcp_server
427```
428 
429**Hooks not firing:**
430- Check `~/.claude/settings.json` has OMEGA hook entries
431- Check `~/.omega/hooks.log` for errors
432 
433## Development
434 
435```bash
436pip3 install -e ".[server,dev]"
437pytest tests/
438ruff check src/              # Lint
439```
440 
441## Uninstall
442 
443```bash
444claude mcp remove omega-memory
445rm -rf ~/.omega ~/.cache/omega
446pip3 uninstall omega-memory
447```
448 
449Manually remove OMEGA entries from `~/.claude/settings.json` and the `<!-- OMEGA:BEGIN -->` block from `~/.claude/CLAUDE.md`.
450 
451## Star History
452 
453[![Star History Chart](https://api.star-history.com/svg?repos=omega-memory/omega-memory&type=Date)](https://star-history.com/#omega-memory/omega-memory&Date)
454 
455## Contributing
456 
457- [Contributing Guide](CONTRIBUTING.md)
458- [Security Policy](SECURITY.md)
459- [Changelog](CHANGELOG.md)
460- [Report a Bug](https://github.com/omega-memory/omega-memory/issues)
461 
462## License
463 
464Apache-2.0 — see [LICENSE](LICENSE) for details.
465