Memory Lifecycle

Every memory follows a defined lifecycle from creation to eventual archival or consolidation.

Memory Pipeline

Creation → Embedding → Dedup Check → Storage → Retrieval → Consolidation → Archival

1. Creation

Memories are created from three operations/surfaces:

• Arena (voice sessions) — via extractAgentMemories() and extractSessionBrief()
• Agent Chat (1:1 text) — via extractFromChat()
• Team Chat (group text) — via extractFromTeamChat()

2. Embedding

Each memory's content is passed through EmbeddingService.embed() using OpenAI's text-embedding-3-small model, producing a 1536-dimensional vector stored in the embedding column.

If embedding fails, the memory is still stored but without vector search capability (embedding = null).

3. Deduplication

Before inserting, MemoryService checks for existing memories with cosine similarity above the threshold (see operations/configuration):

SELECT id, importance FROM agent_memories
WHERE agent_id = $1
  AND embedding IS NOT NULL
  AND (1 - (embedding <=> $2::vector)) > 0.92
LIMIT 1

If a duplicate is found:

• The existing memory's importance is updated to max(existing, new)
• last_accessed_at is refreshed
• No new row is inserted

4. Storage

Non-duplicate memories are inserted with:

• Default importance of 0.5
• status of active
• source_type matching the interaction surface

5. Retrieval

Memories are retrieved via pipeline/scoring|semantic search using the composite scoring formula. Retrieved memories have their last_accessed_at timestamp refreshed via touchMemory().

6. Consolidation

When an agent accumulates >20 active memories, the weekly operations/cron-jobs|consolidation cron clusters similar memories (cosine similarity ≥0.8) and replaces clusters of 3+ with a single consolidated memory via LLM summarization.

Old memories are marked status = 'consolidated'.

7. Archival (Daily Files)

Daily memory files follow a separate three-state lifecycle:

active → warm → archived
  0-7d    7-30d    30d+

The pipeline/context-assembly pipeline only includes active daily files (last 7 days).

Status Values

Agent Memories

Daily Files