Skip to content
Back to search

omega-memory

Persistent memory for AI coding agents

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/omega-memory--omega-memory/badge.svg)](/listings/omega-memory--omega-memory)

HTML

<a href="/listings/omega-memory--omega-memory"><img src="/api/listings/omega-memory--omega-memory/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

OMEGA needs **Python 3.11 or newer**. Check with `python3 --version`: macOS ships Python 3.9, which is too old. If pip answers `No matching distribution found for omega-memory`, that is the reason; install a newer Python first (for example `brew install python@3.12`, or from [python.org](https://www.python.org/downloads/)).

Install OMEGA into its own environment. Homebrew's Python refuses a plain `pip install` (PEP 668), and an isolated install keeps OMEGA's dependencies away from your projects. Pick one:

# pipx
pipx install "omega-memory[server]"

# or uv
uv tool install "omega-memory[server]"

# or a virtual environment
python3.12 -m venv ~/.venvs/omega     # any Python 3.11 or newer
~/.venvs/omega/bin/pip install "omega-memory[server]"
export PATH="$HOME/.venvs/omega/bin:$PATH"

Keep the quotes around `"omega-memory[server]"`: zsh, the default macOS shell, treats bare square brackets as a pattern and fails. The `[server]` extra installs the MCP server, which also runs the hook daemon; without it Claude Code gets no OMEGA tools and no hooks.

Then:

omega setup     # downloads the embedding model, registers the MCP server, installs hooks
omega doctor    # checks every step, and names the fix for anything that failed

`omega setup --dry-run` shows what setup would change without writing or downloading anything.

Claude Desktop

omega setup --client claude-desktop

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

Cursor, Windsurf, Cline, Codex, Antigravity

omega setup --client cursor      # or: windsurf, cline, codex, antigravity

Codex and Antigravity get their config file written; for the others setup prints the JSON block to paste. For any other MCP client, `omega setup --client venv` prints the command and arguments to use. Hooks (automatic capture and surfacing) are available with Claude Code only.

<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, install it into your project's environment:

pip install omega-memory    # Core only, no MCP server
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. Hooks need the MCP server (the hook daemon runs inside it), so a library-only install has no automatic capture or surfacing.

</details>

From Source

git clone https://github.com/omega-memory/omega-memory.git
cd omega-memory
python3.12 -m venv .venv && source .venv/bin/activate
pip install -e ".[server,dev]"
omega setup

`omega setup` will: 1. Create `~/.omega/` (or `$OMEGA_HOME` if you set it) 2. Download the ONNX embedding model, bge-small-en-v1.5 (~130 MB), and a reranker (~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`

If a step fails, the summary marks it `[FAIL]` with the reason and setup exits with an error.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 352 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # OMEGA
  2. **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.
  3. [![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
  4. [![PyPI](https://img.shields.io/pypi/v/omega-memory.svg)](https://pypi.org/project/omega-memory/)
  5. [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
  6. ---
  7. ## The Problem
  8. 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.
  9. - **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.
  10. - **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.
  11. - **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.
  12. - **Vendor lock-in.** Anthropic's Memory Tool only works with Claude. OpenAI's memory only works with GPT. Switch models, lose your memory.
  13. 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.
  14. <!-- TODO: terminal GIF showing memory recall across sessions -->
  15. <!-- mcp-name: io.github.omega-memory/omega-memory -->
  16. ## Quick Install
  17. OMEGA needs **Python 3.11 or newer**. Check with `python3 --version`: macOS ships Python 3.9, which is too old. If pip answers `No matching distribution found for omega-memory`, that is the reason; install a newer Python first (for example `brew install python@3.12`, or from [python.org](https://www.python.org/downloads/)).
  18. Install OMEGA into its own environment. Homebrew's Python refuses a plain `pip install` (PEP 668), and an isolated install keeps OMEGA's dependencies away from your projects. Pick one:
  19. ```bash
  20. # pipx
  21. pipx install "omega-memory[server]"
  22. # or uv
  23. uv tool install "omega-memory[server]"
  24. # or a virtual environment
  25. python3.12 -m venv ~/.venvs/omega # any Python 3.11 or newer
  26. ~/.venvs/omega/bin/pip install "omega-memory[server]"
  27. export PATH="$HOME/.venvs/omega/bin:$PATH"
  28. ```
  29. Keep the quotes around `"omega-memory[server]"`: zsh, the default macOS shell, treats bare square brackets as a pattern and fails. The `[server]` extra installs the MCP server, which also runs the hook daemon; without it Claude Code gets no OMEGA tools and no hooks.
  30. Then:
  31. ```bash
  32. omega setup # downloads the embedding model, registers the MCP server, installs hooks
  33. omega doctor # checks every step, and names the fix for anything that failed
  34. ```
  35. `omega setup --dry-run` shows what setup would change without writing or downloading anything.
  36. ### Claude Desktop
  37. ```bash
  38. omega setup --client claude-desktop
  39. ```
  40. This registers OMEGA as an MCP server in Claude Desktop's config. Restart Claude Desktop to activate.
  41. ### Cursor, Windsurf, Cline, Codex, Antigravity
  42. ```bash
  43. omega setup --client cursor # or: windsurf, cline, codex, antigravity
  44. ```
  45. Codex and Antigravity get their config file written; for the others setup prints the JSON block to paste. For any other MCP client, `omega setup --client venv` prints the command and arguments to use. Hooks (automatic capture and surfacing) are available with Claude Code only.
  46. <details>
  47. <summary><strong>Library-only install (no MCP server)</strong></summary>
  48. If you only need OMEGA as a Python library for scripts, CI/CD, or automation, install it into your project's environment:
  49. ```bash
  50. pip install omega-memory # Core only, no MCP server
  51. ```
  52. ```python
  53. from omega import store, query, remember
  54. store("Always use TypeScript strict mode", "user_preference")
  55. results = query("TypeScript preferences")
  56. ```
  57. This gives you the full storage and retrieval API without running an MCP server. Hooks need the MCP server (the hook daemon runs inside it), so a library-only install has no automatic capture or surfacing.
  58. </details>
  59. ### From Source
  60. ```bash
  61. git clone https://github.com/omega-memory/omega-memory.git
  62. cd omega-memory
  63. python3.12 -m venv .venv && source .venv/bin/activate
  64. pip install -e ".[server,dev]"
  65. omega setup
  66. ```
  67. `omega setup` will:
  68. 1. Create `~/.omega/` (or `$OMEGA_HOME` if you set it)
  69. 2. Download the ONNX embedding model, bge-small-en-v1.5 (~130 MB), and a reranker (~90 MB) to `~/.cache/omega/models/`
  70. 3. Register `omega-memory` as an MCP server (Claude Code auto-detected, or specify `--client`)
  71. 4. Install session hooks into `~/.claude/settings.json`
  72. 5. Add an OMEGA block to `~/.claude/CLAUDE.md`
  73. If a step fails, the summary marks it `[FAIL]` with the reason and setup exits with an error.
  74. ## 60-Second Quickstart
  75. OMEGA works through natural language — no API calls, no configuration. Just talk to Claude.
  76. **1. Tell Claude to remember something:**
  77. > "Remember that the auth system uses JWT tokens, not session cookies"
  78. Claude stores this as a permanent memory with semantic embeddings.
  79. **2. Close the session. Open a new one.**
  80. **3. Ask about it:**
  81. > "What did I decide about authentication?"
  82. OMEGA surfaces the relevant memory automatically:
  83. ```
  84. Found 1 relevant memory:
  85. [decision] "The auth system uses JWT tokens, not session cookies"
  86. Stored 2 days ago | accessed 3 times
  87. ```
  88. That's it. Memories persist across sessions, accumulate over time, and are surfaced automatically when relevant — even if you don't explicitly ask.
  89. ## Key Features
  90. - **Memory & Learning** — Stores decisions, lessons, error patterns, and preferences with semantic search. Claude recalls what matters without you re-explaining everything each session. Tools cover compaction, consolidation, timeline, graph traversal, and checkpoint/resume.
  91. - **Multi-Agent Coordination** *(omega-pro)* — File and branch locking, session management, task queues with dependencies, intent broadcasting, and agent-to-agent messaging, so agents don't overwrite each other's work.
  92. - **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.
  93. - **Knowledge Base** *(omega-pro)* — Ingest PDFs, markdown, web pages, and text files into a searchable knowledge base with semantic chunking.
  94. - **Entity Registry** *(omega-pro)* — Multi-entity corporate memory with relationships, hierarchies, and entity-scoped memories/profiles/documents.
  95. - **Secure Profile** *(omega-pro)* — AES-256 encrypted personal data storage with macOS Keychain integration.
  96. ## How OMEGA Compares
  97. | Feature | OMEGA | Anthropic Memory | Mem0 | Zep |
  98. |---------|:-----:|:----------------:|:----:|:---:|
  99. | Works with any LLM/agent | **Yes** | Claude only | Yes | Yes |
  100. | Your data stays on your machine | **Yes** | Partial* | No | No |
  101. | No cloud dependency | **Yes** | No (needs API) | No | No |
  102. | Semantic search + knowledge graph | **Yes** | No (file CRUD) | $249/mo | Yes |
  103. | Multi-agent coordination | **Yes** *(pro)* | Research preview | No | No |
  104. | Works with Claude Code, Cursor, Claw Code | **Yes** | Claude only | Partial | No |
  105. | Free & open source | **Yes** (Apache 2.0) | No | Freemium | Freemium |
  106. *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).*
  107. **Anthropic Memory is for Anthropic. OMEGA is for everyone.**
  108. ## Architecture
  109. ```
  110. Claude Code · Cursor · Claw Code · Any MCP Client
  111. │ │ │ │
  112. └─────────┴─────┬───┴──────────────┘
  113. │ stdio/MCP
  114. ┌───────────────▼─────────────┐
  115. │ OMEGA MCP Server │
  116. │ core memory tools │
  117. └──┬──────────────────┘
  118. │
  119. ┌────────▼──────────────┐
  120. │ Core Memory Engine │
  121. │ (semantic search, │
  122. │ embeddings, graphs) │
  123. └─────┬─────────────────┘
  124. │
  125. ▼
  126. ┌──────────────────────────────────────┐
  127. │ omega.db (SQLite) │
  128. │ memories | edges | embeddings │
  129. └──────────────────────────────────────┘
  130. ```
  131. Single database, modular handlers. Optional modules (coordination, router, entity, knowledge, profile) are available with [OMEGA Pro](https://omegamax.co/pro) and register into the same server process. No separate daemons, no microservices.
  132. ## MCP Tools Reference
  133. OMEGA runs as an MCP server inside Claude Code. By default it shows the client five tools (`omega_store`, `omega_welcome`, `omega_protocol`, `omega_tools`, `omega_call`) to save context: `omega_tools` lists everything available and `omega_call` runs any of it. Set `OMEGA_CONDENSED=0` in the server's environment to expose every tool directly.
  134. ### Core tools
  135. | Tool | What it does |
  136. |------|-------------|
  137. | `omega_store` | Store a memory (decision, lesson, error, preference, ...) |
  138. | `omega_query` | Search memories: semantic, exact phrase, timeline, or browse |
  139. | `omega_welcome` | Session briefing: recent context, reminders, profile |
  140. | `omega_protocol` | Operating rules for the session |
  141. | `omega_checkpoint` | Save task state for cross-session continuity |
  142. | `omega_resume_task` | Resume a checkpointed task |
  143. | `omega_memory` | Edit, delete, supersede, rate, or link one memory; find similar ones |
  144. | `omega_profile` | Read or update the user profile and preferences |
  145. | `omega_remind` | Set, list, or dismiss time-based reminders |
  146. | `omega_maintain` | Health, consolidation, compaction, backup and restore |
  147. | `omega_stats` | Type breakdown, session stats, weekly digest |
  148. | `omega_reflect` | Find contradictions; trace how a topic's decisions evolved |
  149. | `omega_review` | Review a diff with memory of your codebase's conventions |
  150. | `context_packet` | Compact, task-aware memory packet for the current work |
  151. | `omega_consult_gpt`, `omega_consult_claude` | Ask another model for a second opinion (needs your own API key for that provider) |
  152. [OMEGA Pro](https://omegamax.co/pro) adds coordination, routing, entity, knowledge base, and profile tools.
  153. ## CLI
  154. | Command | Description |
  155. |---------|-------------|
  156. | `omega setup` | Create dirs, download model, register MCP, install hooks (`--dry-run` to preview) |
  157. | `omega doctor` | Verify installation health |
  158. | `omega hooks setup` / `omega hooks doctor` | Install or check the Claude Code hooks only |
  159. | `omega status` | Memory count, store size, model status |
  160. | `omega query <text>` | Search memories by semantic similarity |
  161. | `omega store <text>` | Store a memory with a specified type |
  162. | `omega remember <text>` | Store a permanent preference |
  163. | `omega timeline` | Show memory timeline grouped by day |
  164. | `omega activity` | Show recent session activity overview |
  165. | `omega stats` | Memory type distribution and health summary |
  166. | `omega consolidate` | Deduplicate, prune, and optimize memory |
  167. | `omega compact` | Cluster and summarize related memories |
  168. | `omega backup` | Back up omega.db (keeps last 5) |
  169. | `omega validate` | Validate database integrity |
  170. | `omega logs` | Show recent hook errors |
  171. | `omega migrate-db` | Migrate legacy JSON to SQLite |
  172. | `omega serve` | Run the MCP server (`omega serve --help` for the HTTP daemon) |
  173. ### Free and Pro
  174. Core is free and open source. On the free tier, once the store holds 2,000 memories search switches from semantic search to a plain text match, and new memories stop being stored at 5,000. `omega status` shows where you are. OMEGA Pro removes both limits.
  175. <details>
  176. <summary><strong>Advanced Details</strong></summary>
  177. ### Hooks
  178. All hooks run `fast_hook.py`, which hands the work to the hook daemon inside the MCP server over `~/.omega/hook.sock`. If no server is running, the hooks return at once without doing anything, except reply capture, which runs on its own; none of them blocks Claude Code.
  179. | Hook | Matcher | Handler | Purpose |
  180. |------|---------|---------|---------|
  181. | SessionStart | all | `session_start` | Welcome briefing, session resume |
  182. | Stop | all | `assistant_capture` | Capture decisions and fixes from the reply |
  183. | Stop | all | `session_stop` | Session summary |
  184. | UserPromptSubmit | all | `auto_capture` | Auto-capture lessons/decisions |
  185. | PostToolUse | Edit/Write/NotebookEdit/Bash/Read | `surface_memories` | Surface relevant memories |
  186. Memory text the hooks inject is labelled as stored data, not instructions.
  187. > With OMEGA Pro, additional coordination handlers register automatically: session lifecycle, file/branch claim guards, heartbeat, and git push guards.
  188. ### HTTP daemon (optional)
  189. `omega serve install` runs one shared server under launchd instead of one per session (macOS). It listens on `127.0.0.1:8377`, refuses requests whose Host or Origin is not local, and requires a bearer key kept in `~/.omega/mcp_api_key`. `omega serve migrate-config` points Claude Code at the daemon and writes that key into its config; `omega serve restore-config` switches back.
  190. ### Storage
  191. | Path | Purpose |
  192. |------|---------|
  193. | `~/.omega/omega.db` | SQLite database (memories, embeddings, edges); set `OMEGA_HOME` to move `~/.omega` |
  194. | `~/.omega/profile.json` | User profile |
  195. | `~/.omega/hooks.log` | Hook error log |
  196. | `~/.cache/omega/models/bge-small-en-v1.5-onnx/` | ONNX embedding model |
  197. ### Search Pipeline
  198. 1. **Vector similarity** via sqlite-vec (cosine distance, 384-dim bge-small-en-v1.5)
  199. 2. **Full-text search** via FTS5 (fast keyword matching)
  200. 3. **Type-weighted scoring** (decisions/lessons weighted 2x)
  201. 4. **Contextual re-ranking** (boosts by tag, project, and content match)
  202. 5. **Deduplication** at query time
  203. ### Memory Lifecycle
  204. - **Dedup**: SHA256 hash (exact) + embedding similarity 0.85+ (semantic) + Jaccard per-type
  205. - **Evolution**: Similar content (55-95%) appends new insights to existing memories
  206. - **TTL**: Session summaries expire after 1 day, lessons/preferences are permanent
  207. - **Auto-relate**: Creates `related` edges (similarity >= 0.45) to top-3 similar memories
  208. - **Compaction**: Clusters and summarizes related memories
  209. ### Memory Footprint
  210. - Startup: ~31 MB RSS
  211. - After first query (ONNX model loaded): ~337 MB RSS
  212. - Database: ~10.5 MB for ~242 memories
  213. ### What Gets Modified
  214. `omega setup` modifies these files outside `~/.omega/`:
  215. - `~/.claude.json` — Adds `omega-memory` MCP server entry
  216. - `~/.claude/settings.json` — Adds hook entries
  217. - `~/.claude/CLAUDE.md` — Adds a managed `<!-- OMEGA:BEGIN -->` block
  218. All changes are idempotent.
  219. </details>
  220. ## Troubleshooting
  221. **`omega doctor` shows FAIL on import:**
  222. - Ensure `pip install -e ".[server]"` from the repo root
  223. - Check `python3 -c "import omega"` works
  224. **MCP server fails to start:**
  225. - Install the server extra into the same environment as OMEGA: `pip install "omega-memory[server]"` (or `pipx install --force "omega-memory[server]"`)
  226. **MCP server not registered:**
  227. - Run `omega setup` again, or run the `claude mcp add -s user omega-memory -- ...` command that `omega doctor` prints: it names the Python from OMEGA's own environment
  228. **Hooks not firing:**
  229. - Run `omega hooks doctor`; `omega hooks setup` repairs missing or outdated entries
  230. - Check `~/.omega/hooks.log` for errors
  231. ## Development
  232. ```bash
  233. pip install -e ".[server,dev]"
  234. pytest tests/ # Test suite
  235. ruff check src/ # Lint
  236. ```
  237. ## Uninstall
  238. ```bash
  239. claude mcp remove -s user omega-memory
  240. omega serve uninstall # only if you installed the HTTP daemon
  241. rm -rf ~/.omega ~/.cache/omega
  242. pipx uninstall omega-memory # or: uv tool uninstall omega-memory, or delete the venv
  243. ```
  244. Manually remove OMEGA entries from `~/.claude/settings.json` and the `<!-- OMEGA:BEGIN -->` block from `~/.claude/CLAUDE.md`.
  245. ## Contributing
  246. - [Contributing Guide](CONTRIBUTING.md)
  247. - [Security Policy](SECURITY.md)
  248. - [Changelog](CHANGELOG.md)
  249. - [Report a Bug](https://github.com/omega-memory/omega-memory/issues)
  250. ## License
  251. Apache-2.0. See [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.