API Reference

Your agent forgets everything. Fix that.

Every time you close a session, your AI agent loses all context: decisions made, bugs debugged, preferences learned. OMEGA is an MCP server that gives your agent persistent memory across sessions, projects, and teams. 12 tools, two commands to install.

Quick install

$pip install omega-memory

$omega setup

✓MCP server configured. Your agent now has memory.

See it in action

One workflow. Three sessions.

Here is what it looks like when your agent actually remembers. A real debugging scenario across multiple sessions.

Monday: Debug the auth bug

You spend an hour tracking down a token refresh race condition. Your agent stores the decision and checkpoints progress before you close the session.

Session 1

# Agent discovers the root cause

$omega_store(content="Auth bug root cause: refresh token race condition in /api/auth/refresh. Two concurrent requests both see expired token, both attempt refresh, second one invalidates the first. Fix: add mutex lock on refresh endpoint.", event_type="decision")

✓Stored as decision (priority 4)

# Agent checkpoints before session ends

$omega_checkpoint(task_title="Fix auth race condition", progress="Root cause identified. Mutex approach chosen over token versioning.", next_steps="Implement lock in refreshToken(), add retry logic to API client")

✓Checkpoint saved

Tuesday: Pick up where you left off

New session, new context window. But the agent remembers everything.

Session 2

# New session starts

$omega_welcome()

[WELCOME]Session briefing ready

Recent decisions: auth race condition fix (mutex)

Pending checkpoint: Fix auth race condition

$omega_resume_task(task_title="auth race condition")

[CHECKPOINT]Fix auth race condition

Progress: Root cause identified. Mutex chosen.

Next: Implement lock in refreshToken(), add retry

# Agent continues exactly where it left off

Friday: Same bug, different project

A week later, a different project hits a similar issue. The agent recalls the lesson without you having to explain it again.

Session N

# Working on a different project entirely

$omega_lessons(task="token refresh bug", cross_project=true)

[LESSONS]1 lesson found

(verified) "Auth refresh race condition: concurrent requests both see expired token. Fix with mutex on refresh endpoint, not token versioning."

# Agent applies the fix immediately, no re-investigation

How it works

MCP server. Local SQLite. Zero cloud.

Integration

OMEGA runs as an MCP server. Your AI agent (Claude Code, Cursor, Windsurf, or any MCP-compatible client) discovers and calls these tools automatically. No SDK, no API keys, no wrapper code. Run omega setup and the tools appear in your agent.

Storage

All memories live in a local SQLite database with vector embeddings for semantic search. Your data never leaves your machine. Profile fields are encrypted at rest. You can inspect, back up, or delete the database at any time.

Intelligence

OMEGA does not just store text. It auto-links related memories into a knowledge graph, surfaces relevant context at session start, consolidates duplicates, and prunes stale information. Memories that keep getting accessed get stronger. Ones that never do fade away.

Tool Reference

12 tools. Complete reference.

Every parameter, every default, every return value. Click a tool in the sidebar to jump straight to it.

Session & Context

Called at session boundaries to orient the agent.

omega_welcome

Get a session welcome briefing with recent relevant memories and user profile. Call this first at the start of every session.

Parameters

Parameter	Type	Default	Description
`project`	string	—	Project path for scoping the briefing.
`session_id`	string	—	Session identifier for continuity tracking.

Example

omega_welcome

# Start of session

$omega_welcome(project="/Users/me/myapp")

[WELCOME]Session briefing ready

Profile: 12 encrypted fields

Recent: 3 decisions, 2 lessons

Tasks: 2 pending checkpoints

omega_protocol

Get your coordination playbook: dynamically assembled operating instructions. Call at session start (step 2 after omega_welcome) or when you need protocol guidance.

Parameters

Parameter	Type	Default	Description
`section`	string	—	Section to retrieve: 'memory', 'coordination', 'coordination_gate', 'teamwork', 'context', 'reminders', 'diagnostics', 'entity', 'heuristics', 'git', 'what_next'. Groups: 'solo', 'multi_agent', 'full', 'minimal'.
`project`	string	—	Project path for context-sensitive rules.

Example

omega_protocol

$omega_protocol(section="memory")

[PROTOCOL]Memory section loaded

Store decisions after completing tasks

Query before non-trivial work

Checkpoint when context is filling up

Memory Operations

Core read/write operations for persistent memory.

omega_store

Store a memory with optional type and metadata. Use when the user says 'remember this' or for programmatic capture of decisions, lessons, errors, and preferences.

Parameters

Parameter	Type	Default	Description
`content`req	string	—	Memory content to store (also accepts 'text' as alias).
`event_type`	string	"memory"	Type: memory, session_summary, task_completion, error_pattern, lesson_learned, decision, user_preference, constraint.
`priority`	integer	auto	Priority 1-5 (5 = highest). Auto-set from event type if omitted.
`entity_id`	string	—	Scope this memory to an entity (e.g., 'acme'). Omit for unscoped.
`project`	string	—	Project path for scoping.
`session_id`	string	—	Session identifier.
`metadata`	object	—	Additional metadata to attach.
`agent_type`	string	—	Agent type for sub-agent memory scoping (e.g., 'code-reviewer').

Example

omega_store

$omega_store(

content="Always use bun instead of npm",

event_type="user_preference"

)

✓Stored as user_preference (priority 4)

omega_query

Search memories. Three modes: 'semantic' (default) for meaning-based search, 'phrase' for exact substring match, 'timeline' for recent memories grouped by day.

Parameters

Parameter	Type	Default	Description
`query`	string	—	Search query (or exact phrase when mode='phrase'). Not required for timeline mode.
`mode`	string	"semantic"	Search mode: 'semantic', 'phrase', or 'timeline'.
`limit`	integer	10	Maximum number of results to return.
`event_type`	string	—	Filter by event type.
`entity_id`	string	—	Filter to a specific entity.
`filter_tags`	string[]	—	Hard filter: ALL tags must match (AND logic).
`context_tags`	string[]	—	Context tags for relevance boosting.
`context_file`	string	—	Current file being edited (boosts related results).
`days`	integer	7	Days to look back (only for timeline mode).
`temporal_range`	string[]	—	[start_iso, end_iso] date range filter.
`project`	string	—	Project path for scoping.
`session_id`	string	—	Session identifier.
`agent_type`	string	—	Filter to a specific agent type.
`case_sensitive`	boolean	false	Case-sensitive search (only for phrase mode).
`limit_per_day`	integer	10	Max results per day (only for timeline mode).

Example

omega_query

$omega_query(query="authentication setup")

[RESULTS]3 memories found (semantic)

0.92 "JWT auth configured with RS256..."

0.87 "Auth middleware added to /api/..."

0.81 "User table schema includes..."

omega_memory

Manage individual memories: edit content, delete, give feedback (helpful/unhelpful/outdated), find similar memories, or traverse the relationship graph.

Parameters

Parameter	Type	Default	Description
`action`req	string	—	Operation: 'edit', 'delete', 'feedback', 'similar', or 'traverse'.
`memory_id`req	string	—	Memory node ID to operate on.
`new_content`	string	—	New content (only for action='edit').
`rating`	string	—	Feedback rating: 'helpful', 'unhelpful', or 'outdated' (only for action='feedback').
`reason`	string	—	Optional explanation for feedback.
`limit`	integer	5	Max results for similar search.
`max_hops`	integer	2	Traversal depth 1-5 (only for action='traverse').
`min_weight`	number	0.0	Min edge weight 0.0-1.0 (only for action='traverse').

Example

omega_memory

$omega_memory(

action="feedback",

memory_id="abc123",

rating="outdated",

reason="API endpoint changed in v2"

)

✓Marked as outdated

Workflow

Task continuity, lessons, and reminders across sessions.

omega_checkpoint

Save a task checkpoint: captures current plan, progress, files touched, decisions, and key context. Enables seamless session continuity.

Parameters

Parameter	Type	Default	Description
`task_title`req	string	—	Brief title of the current task.
`progress`req	string	—	What's been completed, in progress, and remaining.
`plan`	string	—	Current plan or goals.
`decisions`	string[]	—	Key technical decisions made.
`files_touched`	object	—	Map of file paths to change summaries.
`key_context`	string	—	Critical context for continuation.
`next_steps`	string	—	What to do next.
`project`	string	—	Project path.
`session_id`	string	—	Session identifier.

Example

omega_checkpoint

$omega_checkpoint(

task_title="Auth system migration",

progress="JWT middleware done, user model updated",

next_steps="Wire up refresh token rotation",

decisions=["RS256 over HS256", "15min access tokens"]

)

✓Checkpoint saved

omega_resume_task

Resume a previously checkpointed task. Retrieves the latest checkpoint with full plan, progress, files, decisions, and next steps.

Parameters

Parameter	Type	Default	Description
`task_title`	string	—	Title of the task to resume (semantic search).
`project`	string	—	Project path to filter checkpoints.
`limit`	integer	1	Number of checkpoints to retrieve.
`verbosity`	string	"full"	'full' = everything, 'summary' = plan + progress + next, 'minimal' = next steps only.

Example

omega_resume_task

$omega_resume_task(task_title="Auth migration")

[CHECKPOINT]Auth system migration

Progress: JWT middleware done, user model updated

Next: Wire up refresh token rotation

Decisions: RS256 over HS256, 15min tokens

omega_lessons

Retrieve cross-session or cross-project lessons learned, ranked by verification count and access frequency.

Parameters

Parameter	Type	Default	Description
`task`	string	—	Task description for relevance filtering.
`project_path`	string	—	Project scope.
`limit`	integer	5	Max lessons to return.
`cross_project`	boolean	false	Search across all projects.
`agent_type`	string	—	Filter to a specific agent type.
`exclude_project`	string	—	Project to exclude (with cross_project=true).
`exclude_session`	string	—	Session ID to exclude.

Example

omega_lessons

$omega_lessons(task="database migration")

[LESSONS]3 lessons found

(5x verified) Always run migrations in a transaction

(3x verified) Test rollback before deploying

(2x verified) Back up production data first

omega_remind

Manage time-based reminders: set new reminders, list active ones, or dismiss by ID.

Parameters

Parameter	Type	Default	Description
`action`	string	"set"	Action: 'set', 'list', or 'dismiss'.
`text`	string	—	What to be reminded about (for action='set').
`duration`	string	—	When to remind, e.g. '1h', '30m', '2d' (for action='set').
`context`	string	—	Optional context for the reminder.
`reminder_id`	string	—	Reminder ID (for action='dismiss').
`status`	string	—	Filter for list: 'pending', 'fired', 'dismissed', or 'all'.
`project`	string	—	Project path.
`session_id`	string	—	Session identifier.

Example

omega_remind

$omega_remind(

text="Check CI pipeline results",

duration="30m"

)

✓Reminder set for 30 minutes

System

Maintenance, analytics, and user profile management.

omega_profile

Read or update user profile, or list stored preferences. Profile data is encrypted at rest.

Parameters

Parameter	Type	Default	Description
`action`	string	"read"	Action: 'read', 'update', or 'list_preferences'.
`update`	object	—	Profile fields to merge (only for action='update').

Example

omega_profile

$omega_profile(action="read")

[PROFILE]User profile

Name: Jason

Preferences: 8 stored

Encrypted fields: 12

omega_maintain

System maintenance: health checks, memory consolidation, compaction, backup/restore, and session cleanup.

Parameters

Parameter	Type	Default	Description
`action`req	string	—	Operation: 'health', 'consolidate', 'compact', 'backup', 'restore', or 'clear_session'.
`dry_run`	boolean	false	Preview only (for compact).
`event_type`	string	"lesson_learned"	Type to compact.
`similarity_threshold`	number	0.6	Jaccard similarity 0.0-1.0 (for compact).
`min_cluster_size`	integer	3	Min cluster size (for compact).
`prune_days`	integer	30	Prune zero-access memories older than N days (for consolidate).
`max_summaries`	integer	50	Max session summaries (for consolidate).
`filepath`	string	—	File path for backup/restore.
`session_id`	string	—	Session to purge (for clear_session).
`warn_mb`	number	350	Warning threshold in MB (for health).
`critical_mb`	number	800	Critical threshold in MB (for health).
`max_nodes`	integer	10000	Max expected nodes (for health).
`clear_existing`	boolean	true	Clear before restore.

Example

omega_maintain

$omega_maintain(action="health")

[HEALTH]System status

Memories: 663 nodes, 4.2 MB

Status: healthy

Last backup: 2h ago

omega_stats

Memory analytics: type breakdown, session stats, weekly digest, or forgetting audit log.

Parameters

Parameter	Type	Default	Description
`action`req	string	—	Which stats to retrieve: 'types', 'sessions', 'digest', or 'forgetting_log'.
`days`	integer	7	Days for digest.
`limit`	integer	50	Max entries for forgetting_log.
`reason`	string	—	Filter forgetting_log by reason.

Example

omega_stats

$omega_stats(action="types")

[STATS]Memory type breakdown

decision: 142

lesson_learned: 89

user_preference: 34

error_pattern: 28

memory: 370

Ready to build persistent memory?

Get started with OMEGA in under a minute. Open source, local-first, Apache 2.0.

Get Started View on GitHub

Benchmarks Compare How It Works Blog Whitepaper