Installation

Install from PyPI

=== "Core (memory + coordination)"

```bash
pip install omega-memory
```

Includes all 25 MCP tools. This is everything most users need.

=== "With LLM routing"

```bash
pip install omega-memory[router]
```

Adds 10 routing tools to send prompts to the optimal model across Anthropic, OpenAI, Google, Groq, and xAI.

=== "With entity registry"

```bash
pip install omega-memory[entity]
```

Adds 8 entity tools for tracking companies, LLCs, and organizational structures. Includes encryption support.

=== "With PDF ingestion"

```bash
pip install omega-memory[knowledge-pdf]
```

Adds document ingestion with Docling for high-quality PDF extraction with native markdown output.

For a lighter alternative using pdfplumber only:

```bash
pip install omega-memory[knowledge-pdf-lite]
```

=== "With encryption"

```bash
pip install omega-memory[encrypt]
```

Adds AES-256 encrypted secure profile storage with macOS Keychain integration.

=== "With cloud sync"

```bash
pip install omega-memory[cloud]
```

Adds Supabase cloud sync for cross-device memory sharing.

=== "Everything"

```bash
pip install omega-memory[full]
```

Installs all optional modules: router, entity, knowledge-pdf, encrypt, and cloud.

Install from source

git clone https://github.com/omega-memory/omega.git
cd omega
pip install -e ".[dev]"
omega setup

The [dev] extra includes test dependencies (pytest, ruff, etc.) in addition to core functionality.

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 embedding model — Fetches bge-small-en-v1.5 (~90MB) to ~/.cache/omega/models/ for local semantic search. No API calls needed.
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 7 hook entries to ~/.claude/settings.json for automatic memory capture, surfacing, coordination, and guard rails.
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

Example output:

OMEGA Doctor — v1.2.0
─────────────────────
[OK] Python 3.12.4
[OK] Database: ~/.omega/omega.db (254 memories)
[OK] Embedding model: bge-small-en-v1.5-onnx
[OK] MCP server registered in ~/.claude.json
[OK] 7 hooks installed in ~/.claude/settings.json
[OK] CLAUDE.md has OMEGA block

All checks passed.

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:

omega setup --uninstall   # Removes hooks, MCP entry, and CLAUDE.md block
pip 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.