Memory Types

Every memory has a memory_type field: short_term or long_term. This controls lifecycle behaviour.

Short-term

Short-term memories are temporary. They can have a ttl (time-to-live, in seconds) and expire automatically once it elapses.

curl -X POST http://localhost:4545/api/v1/memories \
  -H "Content-Type: application/json" \
  -d '{
    "content": "User is currently working on the Q3 report.",
    "memory_type": "short_term",
    "ttl": 86400,
    "tags": ["task", "active"]
  }'

Use short-term for:

• Current session context
• Active task state
• Temporary user intent (“they just asked about X”)
• Anything that’s only relevant for hours or days

Long-term

Long-term memories persist indefinitely (subject to importance decay and active forgetting). They are the primary storage for durable knowledge.

curl -X POST http://localhost:4545/api/v1/memories \
  -H "Content-Type: application/json" \
  -d '{
    "content": "User prefers to communicate in bullet points rather than paragraphs.",
    "memory_type": "long_term",
    "importance": 0.9,
    "tags": ["preference", "communication"]
  }'

Use long-term for:

• User preferences
• Biographical context
• Domain knowledge about the user’s situation
• Facts that remain relevant across many sessions

Flashbulb memories

A long-term memory can also be created as a flashbulb memory — a protected memory representing something emotionally significant. Pass arousal >= 0.8 on store_memory:

curl -X POST http://localhost:4545/api/v1/memories \
  -H "Content-Type: application/json" \
  -d '{
    "content": "User said the outage cost them a major client — they were furious.",
    "emotional_valence": -0.8,
    "arousal": 0.9
  }'

Creating a memory with arousal >= 0.8 automatically:

• Force-promotes it to long_term, regardless of the memory_type field supplied
• Floors its importance at 0.9
• Exempts it from importance decay and active forgetting for 30 days (tracked via flashbulb_until)

This only happens at creation time — raising arousal on an existing memory via update_memory does not retroactively make it a flashbulb memory. See Memory Lifecycle for full details on flashbulb protection and active forgetting.

Importance score

Both types accept an importance field (0.0–1.0, default 0.5). Importance affects:

• Search ranking — higher importance memories rank higher in hybrid search
• Decay rate — importance decay reduces long-term memories’ scores by ~0.5%/day; flashbulb memories are exempt while protected

Promotion

Short-term memories are promoted to long-term in three ways:

• Manually, via the promote_to_longterm MCP tool or POST /api/v1/memories/{id}/promote
• Automatically at creation, for flashbulb memories (arousal >= 0.8), as described above
• Automatically at TTL expiration, if the memory’s access_count is at or above the promotion threshold (3) when its ttl elapses — otherwise it’s archived instead. See Memory Lifecycle for details.