Installation

Install from PyPI

OMEGA needs Python 3.11 or newer. The python3 that comes with macOS is 3.9, which is too old.

Install OMEGA with pipx, which gives it its own Python environment and puts the omega command on your PATH:

pipx install "omega-memory[server]"

Keep the quotes: zsh, the default shell on macOS, reads the square brackets as a file pattern and stops with "no matches found". The [server] extra installs the MCP server; without it omega setup still succeeds, but your AI client cannot start OMEGA.

No pipx yet? On macOS run brew install pipx, then pipx ensurepath, and open a new terminal. On an Intel Mac, if the install fails under Python 3.14, run pipx install --python python3.12 "omega-memory[server]".

A plain pip install into Homebrew's Python fails with "externally-managed-environment" (PEP 668). If you prefer a virtual environment to pipx:

python3.12 -m venv ~/.omega-venv
~/.omega-venv/bin/pip install "omega-memory[server]"
~/.omega-venv/bin/omega setup

Optional extras

To add an extra to an existing pipx install, install it into OMEGA's environment:

pipx runpip omega-memory install "omega-memory[encrypt]"

LLM routing, the entity registry, the knowledge base and cloud sync come with OMEGA Pro (below); they are not extras. PDF ingestion in the knowledge base uses Docling, with pdfplumber as the fallback. Add them to OMEGA's environment with pipx runpip omega-memory install docling pdfplumber, or pipx runpip omega-memory install pdfplumber for the lighter extractor on its own.

OMEGA Pro

OMEGA Pro is not published on PyPI. After you buy it, run setup and then activate your license in the same environment as OMEGA:

omega setup --client claude-code
omega activate YOUR-LICENSE-KEY

Run setup first. omega activate checks your license, then downloads the private omega-memory-pro package and installs it next to OMEGA, upgrading Core if Pro needs a newer release. Your Pro dashboard has your key, setup steps for each client, and the Pro wheel if you would rather install it yourself: pipx inject omega-memory ~/Downloads/omega_memory_pro-*.whl.

Pro unlocks apply-capable context maintenance, including backfill-context-packet --apply and maintain-context-packet. Core users keep context_packet, evals, diagnostics, and dry-run backfill.

After installing or upgrading Pro, restart your MCP client or daemon and verify that the Pro plugin is visible. This runs the check with the Python from OMEGA's own environment:

"$(dirname "$(readlink -f "$(command -v omega)")")/python" - <<'PY'
from omega.plugins import discover_plugins, has_capability
print([p.__class__.__name__ for p in discover_plugins()])
print(has_capability("pro_tools"))
PY

With an active license, the output should include OmegaPlatformPlugin and True. If it prints False, reinstall the latest private Pro wheel from the dashboard and restart the MCP process.

Install 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

The [dev] extra adds test dependencies (pytest, ruff, etc.); [server] adds the MCP server.

Requirements

Run setup

After installing, run the setup wizard:

omega setup

This performs 5 steps:

1. Creates ~/.omega/ — The storage directory for your database, profile, secrets, and logs.
2. Downloads the ONNX models — Fetches the all-MiniLM-L6-v2 embedding model and a reranker (about 270MB together) to ~/.cache/omega/models/ for local semantic search. No API calls needed. omega setup --download-model adds bge-small-en-v1.5, which finds related memories more reliably.
3. Registers the MCP server — Adds an omega-memory entry to ~/.claude.json so Claude Code can spawn OMEGA on demand via stdio transport.
4. Installs hooks — Adds 5 hook entries to ~/.claude/settings.json for automatic memory capture and surfacing.
5. Updates CLAUDE.md — Adds a managed <!-- OMEGA:BEGIN --> block to ~/.claude/CLAUDE.md with instructions for using memory and coordination tools.

Setup is idempotent

You can run omega setup multiple times safely. It will update existing configuration without duplicating entries.

Verify the installation

omega doctor

This checks:

• Python version and OMEGA package version
• SQLite database exists and is accessible
• Embedding model is downloaded and loadable
• MCP server entry is registered in ~/.claude.json
• Hooks are installed in ~/.claude/settings.json
• CLAUDE.md contains the OMEGA block

If doctor reports issues

Run omega setup again to repair missing configuration. If the embedding model download fails, check your internet connection — the model is fetched once from Hugging Face and cached locally.

Uninstalling

To remove OMEGA completely:

1. Remove the MCP server from your client. For Claude Code: claude mcp remove -s user omega-memory.
2. Delete the OMEGA hook entries (the ones that run fast_hook.py) from ~/.claude/settings.json.
3. Delete the block between <!-- OMEGA:BEGIN and <!-- OMEGA:END --> from ~/.claude/CLAUDE.md.
4. Remove the package and its data:

pipx uninstall omega-memory
rm -rf ~/.omega            # Delete all stored memories (irreversible)
rm -rf ~/.cache/omega      # Delete cached embedding models

Next steps

• Quickstart — Store your first memory and see it come back in a new session.
• Configuration — Customize storage paths, hooks, and environment variables.