Working with Memory

Overview

OMEGA stores memories as semantically embedded nodes in a graph, enabling cross-session recall for AI coding agents. Each memory has:

• Event type: decision, lesson_learned, error_pattern, task_completion, session_summary, user_preference, checkpoint
• Priority: 1-5 (5 = highest). Auto-set from event type if omitted.
• Tags: Auto-extracted from content for filtering and boost scoring.
• TTL: Time-to-live varies by type (session summaries expire in 1 day; lessons and preferences are permanent).
• Entity scope: Optionally scope memories to a corporate entity (e.g., entity_id="acme").

Memories are stored in SQLite with FTS5 full-text search and sqlite-vec vector embeddings (bge-small-en-v1.5, ONNX CPU-only). Retrieval blends semantic similarity (70%) with BM25 text search (30%), boosted by word overlap, tag matching, and feedback signals.

Use memory when you need to persist decisions, capture lessons from debugging sessions, save task progress across context windows, or recall prior context before starting work.

Quick Example

# Store a decision
omega_store(content="Use PostgreSQL for the analytics service — need window functions and JSONB", event_type="decision")

# Query later
omega_query(query="database choice for analytics")

# User says "remember this"
omega_remember(text="Deploy window is Tuesdays 2-4pm PST")

Tools Reference

Common Workflows

Storing Memories

There are three ways memories enter the system:

1. Explicit remember --- when the user says "remember this":

omega_remember(text="The staging environment uses port 8443")

2. Typed store --- for structured capture with metadata:

omega_store(
    content="Switched from REST to gRPC for inter-service calls — 3x latency improvement",
    event_type="decision",
    priority=4,
    entity_id="acme"
)

3. Auto-capture --- hooks detect decisions and lessons in conversation and store them automatically via the UserPromptSubmit hook. No manual action needed.

Querying Memories

Semantic search --- finds conceptually related memories:

omega_query(query="authentication flow for mobile app")

Filtered search --- narrow by type, tags, entity, or time:

omega_query(
    query="database migration",
    event_type="decision",
    filter_tags=["postgres"],
    entity_id="acme",
    temporal_range=["2026-01-01", "2026-02-01"]
)

Context-aware search --- boost results relevant to what you are editing:

omega_query(
    query="error handling patterns",
    context_file="src/api/handler.py",
    context_tags=["python", "fastapi"]
)

Exact phrase search --- for specific strings, error messages, or known terms:

omega_phrase_search(phrase="ECONNREFUSED", event_type="error_pattern")

Cross-session lessons --- ranked by how often they have been verified:

omega_lessons(task="setting up CI pipeline", limit=5, cross_project=True)

Memory Types and TTLs

Context Virtualization

When the context window is getting full (>70% capacity), checkpoint your work:

omega_checkpoint(
    task_title="API redesign Phase 2",
    plan="Migrate all endpoints to v2 schema",
    progress="Completed users and orders endpoints. Auth endpoints remain.",
    files_touched={"src/api/users.py": "Migrated to v2 schema", "src/api/orders.py": "Migrated to v2 schema"},
    decisions=["Keep backward compat for v1 until March", "Use Pydantic v2 model_validator"],
    key_context="V2 schema uses camelCase keys. Auth endpoints depend on the new JWT middleware in src/middleware/auth.py.",
    next_steps="Migrate src/api/auth.py and src/api/billing.py, then update integration tests."
)

In a new session, resume where you left off:

omega_resume_task(task_title="API redesign", verbosity="full")

Verbosity levels:

• full --- plan + progress + files + decisions + key context + next steps
• summary --- plan + progress + next steps
• minimal --- just next steps

Graph Traversal

Memories form a graph through automatic relationship edges. Traverse to discover related context:

omega_traverse(memory_id="mem_abc123", max_hops=2, min_weight=0.3)

Find memories similar to a known one:

omega_similar(memory_id="mem_abc123", limit=5)

Maintenance

Consolidate --- prune stale memories and clean up (run weekly, auto-triggered by hooks):

omega_consolidate(prune_days=30, max_summaries=50)

Compact --- cluster similar memories into summary nodes (run biweekly):

omega_compact(event_type="lesson_learned", similarity_threshold=0.6, min_cluster_size=3)

Preview clusters without compacting:

omega_compact(dry_run=True)

Timeline --- review what was captured recently:

omega_timeline(days=7, limit_per_day=10)

Feedback --- improve retrieval quality over time:

omega_feedback(memory_id="mem_abc123", rating="helpful")
omega_feedback(memory_id="mem_xyz789", rating="outdated", reason="We switched to Redis")

Tips

• Query before you work. Run omega_query at the start of non-trivial tasks to surface prior decisions, gotchas, and lessons. This prevents re-discovering known issues.
• Check OMEGA on errors. Before debugging from scratch, search for prior solutions with omega_phrase_search on the error message.
• Let hooks do the work. Auto-capture detects decisions and lessons in conversation. You do not need to manually store everything.
• Checkpoint early. Do not wait until the context window is completely full. Checkpoint at major milestones or when you notice things slowing down.
• Use entity scoping. If you work across multiple organizations or projects, scope memories with entity_id to keep contexts separate.
• Rate memories. Using omega_feedback with helpful or unhelpful directly affects future retrieval scoring. Marking memories outdated dampens them.
• Compact periodically. If you accumulate many similar lessons (e.g., repeated debugging insights for the same system), omega_compact clusters them into clean summaries.
• Phrase search for exact matches. Semantic search is fuzzy by design. When you need an exact error message or specific identifier, use omega_phrase_search.
• Temporal ranges narrow results. If you know roughly when something happened, add temporal_range to your query to avoid pulling in old, irrelevant memories.
• Backup regularly. omega_backup(filepath="~/omega-backup.json") exports everything. The auto-maintenance hooks back up weekly, but manual backups before risky operations are wise.