Memory System

Long-term memory for agents to remember and recall information across conversations.

Configuration

Memory is enabled via environment variables:

# Required: Your memory user ID (UUID)
export MEMORY_USER_ID="3bfa14ac-b514-475c-a142-4442a90c05a5"

# Optional: Context identifier (defaults to cli:<run-id>)
export MEMORY_CONTEXT="cli:my-session"

To find your user ID:

sqlite3 ~/.local/share/omni/memory.db "SELECT DISTINCT user_id FROM memories"

Overview

The memory system has two modes:

Passive - Relevant memories auto-injected into context based on conversation
Active - Explicit remember and recall tools for precise control

Active Memory (Tools)

remember

Store information for future reference:

{
  "content": "User prefers dark mode and uses vim keybindings",
  "context": "mentioned during IDE setup discussion",
  "tags": ["preferences", "editor"]
}

When to use:

User shares personal facts, preferences, or context
Important decisions or agreements
Technical details specific to the user/project
Corrections to previously stored information

Best practices:

Be specific and factual
Include context for why this matters
Use consistent tags for categorization
Don’t store transient information (today’s weather, etc.)

recall

Search memory for relevant information:

{
  "query": "editor preferences",
  "limit": 5
}

When to use:

Before making assumptions about user preferences
When context seems missing from conversation
To check if you’ve discussed something before
To find related past decisions

Best practices:

Use semantic queries (meaning-based, not keyword-exact)
Start with broad queries, narrow if too many results
Cross-reference multiple recalls for complex topics

Passive Memory (Auto-injection)

When enabled, the system automatically:

Knowledge injection - Recalls semantically similar memories based on current conversation
Temporal context - Includes recent conversation history
Contradiction detection - Warns if recalled memories conflict

You don’t need to call recall for basic context - it’s already in your system prompt under <knowledge> or <conversation_history>.

Memory Identity

Memory is scoped by identity:

Owner - Who this data belongs to (user ID, org, etc.)
Context - Session/conversation identifier

Examples:

Telegram: owner=user-uuid, context=telegram:12345
CLI: owner=user-uuid, context=cli:session-abc
Agent: owner=agentd, context=run:task-123

Deduplication

The system automatically:

Merges duplicates (≥95% similarity) - keeps most recent
Links related (85-95% similarity) - creates graph connections
Filters superseded - hides memories that were updated

Examples

Storing preferences

User: "I prefer functional programming and use Haskell at work"

remember({
  content: "User prefers functional programming, uses Haskell professionally",
  context: "shared during programming discussion",
  tags: ["preferences", "technical", "languages"]
})

Storing corrections

User: "Actually I switched from VS Code to Neovim"

remember({
  content: "User uses Neovim (switched from VS Code)",
  context: "correction to previous editor preference",
  tags: ["preferences", "editor", "correction"]
})

Recalling before answering

User: "What editor config should I use?"

// Before answering, check memory
recall({ query: "editor preferences IDE", limit: 3 })

// Then personalize response based on what you find

When NOT to Remember

Don’t store:

Transient facts (weather, time-sensitive info)
Information already in project files
Generic knowledge (not user-specific)
Sensitive data without explicit permission
Every single fact mentioned (be selective)

Troubleshooting

Conflicting memories?

Check <contradictions> in your context
Use remember with correction tag to update

Missing context?

Passive recall may not have found it
Use explicit recall with different queries
Information may not have been stored

Too much context?

System filters by relevance and recency
Recent memories weighted higher
Superseded memories hidden