Memory Tiers

Athena models memory the way cognitive science does: a small, fast working memory; a consolidating mid-term store; and a durable long-term store of distilled knowledge. Each tier has its own datastore, granularity, and lifetime.

	STM	MTM	LTM
Holds	Raw events	Cognitive chains (summarized topics)	Knowledge graph (entities + relations)
Granularity	One message/thought/action	One topic segment	One fact
Stores	Redis + MongoDB	MongoDB + Milvus	ArangoDB
Lifetime	2h window / durable log	Until archived (heat-based)	Permanent
Written by	API (synchronous)	Workers (async)	Promoter (async)

STM: Short-Term Memory

Short-Term Memory is the agent's working memory: the verbatim, unprocessed record of the current conversation. It holds the last few events exactly as they happened (every word, every tool call), exists so an agent can recall what was just said without carrying its own context, and is the only tier written synchronously by the API. It answers one question: what is happening right now?

Mechanically, STM is two writes per event:

Hot path (Redis). Every event is LPUSHed to a per-scope list under the key stm:{tenantId}:{userId}:{agentId}, trimmed to a sliding window of STM_CACHE_MAX_TURNS (default 10) and expiring after STM_CACHE_TTL (default 2 hours) of inactivity. GetContext reads this list; it's a single LRANGE.

Durable path (MongoDB). The same event is simultaneously inserted into cognitive_events. Redis can evaporate; MongoDB is the system of record and the source the worker partitions into chains.

Event coalescing. Automation floods are absorbed at the door: consecutive observation events carrying the same execution_id and step_id are merged into one event (content replaced, metadata merged, coalesced_count incremented) instead of consuming window slots. A CI pipeline emitting 40 log lines occupies one STM slot, not 40.

Event anatomy: four types × three roles:

role: user | agent | system
type: message | thought | action | observation

plus optional metadata (e.g. workflow_id, execution_id, origin_service) and an optional blob payload (uploaded to object storage, referenced by URI). See Storing Memory.

MTM: Mid-Term Memory

Mid-Term Memory is episodic memory: a compressed, searchable record of conversations that have ended. Where STM keeps every word of the current topic, MTM keeps the gist of past topics, organized as one summarized unit per topic (a cognitive chain) rather than one entry per message. It exists so an agent can answer "what did we discuss about X last week?" without replaying transcripts. It answers the question: what has happened?

A chain is born when the conversation moves on: the worker cuts the finished topic segment out of STM and distills it into a MongoDB document in cognitive_chains carrying:

• an LLM-written summary, topic, and extracted entities
• a quality score from the validation gate
• a heat score and recall metadata driving its lifecycle (Heat & Decay)
• one embedding stored in Milvus, making the chain semantically searchable

Chains are living documents: a returning conversation on the same topic can merge into an existing chain rather than spawn a duplicate, and every retrieval warms the chain's heat.

MTM is what SearchMemory searches and what GetContext blends in as relevant_pages: memory that has left the window but is still fresh enough to matter.

LTM: Long-Term Memory

Long-Term Memory is semantic memory: durable knowledge about the user's world, detached from any conversation. It stores facts ("John uses Go", "John works on the payments service") as a graph of entities and typed relationships, not summaries of what was said. Conversations are the evidence; LTM keeps the conclusions. It answers the question: what is true?

Facts enter the graph through promotion. Chains that stay hot cross the promotion threshold and get read for knowledge: an LLM extracts subject–relation–object triples from the chain summary, which are UPSERTed into the athena_ltm graph in ArangoDB:

• Vertex collections: Identities, Concepts, Tools, Projects (+ Communities from analytics)
• Edge collection: MemoryEdges, with a whitelisted relation vocabulary (USES, WORKS_ON, BUILT_FOR_CLIENT, STRUGGLES_WITH, EXHIBITS, EXPRESSED_INTEREST, RELATES_TO), per-edge confidence, and a frequency weight that increments every time the same fact is re-observed

LTM is deduplicated by construction: observing "John uses Go" ten times produces one edge with weight: 10, not ten edges. Retrieval traverses 1–2 hops from matched entities, filtered to confidence >= 0.5. Full mechanics in Promotion & the Knowledge Graph.

How a memory moves through the tiers

sequenceDiagram
    participant A as Agent
    participant STM as STM (Redis+Mongo)
    participant W as Worker
    participant MTM as MTM (Mongo+Milvus)
    participant P as Promoter
    participant LTM as LTM (ArangoDB)
    A->>STM: StoreInteraction
    Note over STM: instant recall window
    W->>STM: detect topic break
    W->>MTM: summarize segment → chain + embedding
    P->>MTM: heat ≥ 0.3?
    P->>LTM: extract triples → UPSERT graph
    Note over MTM: heat < 0.1 & idle 7d → archived

The tiers are progressively lossy in form but durable in meaning: STM keeps every word for hours, MTM keeps the gist for as long as it stays warm, LTM keeps the facts forever.