Memory System

The memory system enables persistent, contextual conversations by storing and retrieving relevant information about your interactions. Unlike traditional chat applications that forget everything between sessions, Iris builds a growing understanding of you over time.

Two Layers of Context

Iris uses two complementary systems for remembering what matters:

1. Truths - Stable, core facts that are relevant across conversations. Your name, key relationships, and fundamental preferences. Truths are earned through behavioral evidence - memories that consistently prove useful get promoted automatically.

2. Memories - Contextual information retrieved based on what you're currently discussing. Memories about cooking surface when you're planning dinner, not when you're debugging code.

This separation ensures Iris always knows the essentials while keeping context focused on what's relevant to the current conversation.

NOTE

Memories and Truths are stored globally across all threads — your preferences, relationships, and core facts are searchable regardless of which thread you're in. However, memory recall is thread-scoped: search queries are generated from the current thread's conversation, so the memories that surface are relevant to what you're discussing right now, not influenced by other threads. Thread-specific context (conversation history, summaries) is handled by the thread system.

Memory Retrieval

When you send a message, Iris retrieves relevant context through semantic search:

1. Query Generation: An LLM analyzes recent conversation turns from the current thread and generates search queries
2. Vector Search: Queries are embedded and compared against your full memory pool using cosine similarity
3. Ranking: Results are scored and ranked by the composite scoring formula
4. Filtering: Only memories above the similarity threshold (default: 0.38) are included

Query generation is thread-scoped — only conversation turns from the active thread inform what to search for. The search itself runs against all your memories globally. This means if you're discussing a recipe in one thread, cooking memories surface there without being influenced by a debugging conversation in another thread.

Memory Types

Type	Description
fact	Objective information about the user
preference	Likes, dislikes, and preferences
goal	Things the user wants to achieve
event	Past or upcoming events
skill	Capabilities and expertise
relationship	People and relationships
habit	Regular behaviors and routines
context	Situational information

Scoring

Memories are ranked by a composite score that balances multiple factors:

score = (semantic × 0.60) + (recency × 0.25) + (frequency × 0.15)

Score Components

Component	Weight	What it measures
Semantic similarity	60%	How closely the memory relates to the current conversation, measured by cosine similarity between embeddings
Recency	25%	How recently the memory was created or accessed, decaying linearly over 90 days
Frequency	15%	How often the memory has been retrieved, indicating ongoing relevance

Type Bonuses

Certain memory types receive score bonuses because they tend to be more relevant:

• Relationships: +0.10 (people you know are often contextually important)
• Preferences and goals: +0.05 (these shape how Iris should respond)
• Recent events: +0.10 (upcoming or recent events are likely relevant)

Example Scoring

Consider a memory: "Prefers morning meetings before 10am" created 30 days ago, accessed 5 times.

If you ask "When should we schedule our call?":

• Semantic similarity might be 0.85 (highly relevant)
• Recency: ~0.67 (30/90 days decay)
• Frequency: ~0.50 (normalized)

Raw score: (0.85 × 0.60) + (0.67 × 0.25) + (0.50 × 0.15) = 0.75

With the preference bonus (+0.05): 0.80

Configuration

Setting	Default	Description
memory.max_results	7	Maximum memories to include from semantic search
memory.similarity_threshold	0.38	Minimum similarity score to include a memory

TIP

If memories seem stale or irrelevant, adjust the scoring weights in config. Increase recency to prioritize recent memories, or semantic to prioritize relevance.

How Memories Are Created

1. Automatic Extraction - Background job analyzes conversations and extracts memorable facts
2. Consolidation - Similar memories are merged nightly, with generation tracking to enable organic memory evolution
3. Promotion to Truths - Frequently accessed memories can be promoted to Truths through distillation
4. Manual Tools - Iris can store, update, or delete memories directly during conversation

Viewing Memories

The Memories page in the UI shows all your memories with filtering and search. Consolidated memories display their generation level (e.g., "Merged Gen 2") to show how many times they've been consolidated. The Insights page includes consolidation statistics in the Memory Insights panel.

Troubleshooting Memory Retrieval

Memories not surfacing

If relevant memories aren't appearing in conversations:

1. Check the similarity threshold - The default (0.38) is fairly permissive. If memories still aren't surfacing, the search queries may not match well. Try rephrasing your question to use similar language to how the memory is stored.

2. Verify memories exist - Check the Memories page to confirm the information was actually stored.

3. Check if it should be a Truth - If a memory is important enough to surface in most conversations, it might be better suited as a Truth. Create it manually or wait for distillation to promote it.

Too many irrelevant memories

If Iris seems to include memories that aren't helpful:

1. Raise the similarity threshold - Increase memory.similarity_threshold in config to be more selective.

2. Reduce max results - Lower memory.max_results to include fewer total memories.

Stale memories dominating

If old memories keep appearing over newer, more relevant ones:

1. Increase recency weight - The default recency weight (0.15) is relatively low. Increasing it prioritizes recent memories.

2. Let consolidation run - Consolidation merges similar memories, which can help surface the most current version of information.

3. Update outdated memories - Use the update_memory tool to correct information rather than creating new memories.