Configuration

Storage paths

OMEGA stores all data locally. Here's where everything lives:

Portable storage

Set the OMEGA_HOME environment variable to move the storage directory anywhere. The cache directory for models stays at ~/.cache/omega/ regardless.

Files modified outside ~/.omega

omega setup modifies three files in your Claude Code configuration:

~/.claude.json — MCP server registration

Adds an omega-memory entry to the mcpServers section:

{
  "mcpServers": {
    "omega-memory": {
      "command": "python3",
      "args": ["-m", "omega.server.mcp_server"],
      "env": {},
      "timeout": 3600
    }
  }
}

This tells Claude Code how to spawn the OMEGA MCP server.

~/.claude/settings.json — Hook entries

Adds 7 hook entries that power automatic memory capture, surfacing, and coordination. See the Hooks section below for details.

~/.claude/CLAUDE.md — Agent instructions

Adds a managed block between <!-- OMEGA:BEGIN --> and <!-- OMEGA:END --> markers with instructions for using memory and coordination tools. This block is updated on each omega setup run.

Environment variables

=== "Set temporarily"

```bash
OMEGA_HOME=/path/to/storage omega doctor
```

=== "Set permanently (zsh)"

```bash
echo 'export OMEGA_HOME=/path/to/storage' >> ~/.zshrc
source ~/.zshrc
```

Hooks

OMEGA uses 7 hook processes (batched from 11 handlers) that run automatically during Claude Code sessions. All hooks are fail-open — if a hook errors, it logs to ~/.omega/hooks.log and lets the operation proceed.

Disabling hooks

To disable a specific hook, remove its entry from ~/.claude/settings.json. To disable all hooks:

omega setup --uninstall-hooks

To reinstall them later:

omega setup --install-hooks

Disabling hooks reduces functionality

Without hooks, OMEGA still works as an MCP tool server — you can manually query and store memories. But automatic capture, surfacing, coordination guards, and session management won't function.

MCP server

OMEGA runs as a stdio MCP server spawned by Claude Code on demand. Key characteristics:

• Transport: stdio (stdin/stdout JSON-RPC). No network ports, no HTTP.
• Lifecycle: Claude Code spawns the server process when it first needs an OMEGA tool. The server stays alive for the duration of the session.
• Idle timeout: Auto-shuts down after 1 hour (3600s) of inactivity. Configurable via OMEGA_IDLE_TIMEOUT.
• Memory: ~31MB at startup, ~337MB after first query (loads ONNX embedding model into RAM).
• Tool count: Up to 70 tools depending on installed extras (24 memory + 28 coordination + 10 router + 8 entity).

Checking server status

# Verify MCP registration
omega doctor

# Check if the server process is running
ps aux | grep omega.server.mcp_server

Router configuration (optional)

If you installed omega-memory[router], configure API keys in ~/.omega/secrets.json:

{
  "anthropic_api_key": "sk-ant-...",
  "openai_api_key": "sk-...",
  "google_api_key": "...",
  "groq_api_key": "gsk_...",
  "xai_api_key": "xai-..."
}

Protect your secrets

omega setup creates secrets.json with chmod 600 (owner read/write only). Never commit this file to version control.

You can also set API keys as environment variables:

export ANTHROPIC_API_KEY="sk-ant-..."
export OPENAI_API_KEY="sk-..."
export GOOGLE_API_KEY="..."
export GROQ_API_KEY="gsk_..."
export XAI_API_KEY="xai-..."

Cloud sync configuration (optional)

If you installed omega-memory[cloud], configure Supabase credentials:

omega cloud setup

This prompts for your Supabase URL and anon key, stored in ~/.omega/secrets.json. Sync runs automatically:

• Pull: Once per day at session start
• Push: At session end after sync_all

Auto-maintenance

OMEGA runs background maintenance tasks on a schedule, tracked by marker files in ~/.omega/:

All maintenance runs at session start and is non-blocking.

Next steps

• Quickstart — Try OMEGA hands-on with your first memories.
• MCP Tools Reference — Full documentation for all 70 MCP tools.