making human memory.

Memory Object Structure

Soul doesn't store transcripts. It stores opinionated memories about who someone is, not what they said, with saliency, certainty, reasoning, and curiosity. Each memory is a short, single-thought summary.

Saliency Scoring

Not all memories deserve equal persistence. In the paper, most new memories default to saliency 2, while higher scores are reserved for patterns confirmed across interactions or core identity signals.

FUNCTION score_saliency(observation):
  // 5: core identity, life-defining, rare
  IF is_core_identity(observation):
    RETURN 5

  // 4: significant pattern or turning point, usually confirmed over time
  IF is_significant_pattern(observation):
    RETURN 4

  // 3: a real insight about who they are
  IF is_real_insight(observation):
    RETURN 3

  // 1: fleeting observation
  IF is_fleeting(observation):
    RETURN 1

  // Default most new memories to 2
  RETURN 2

Memory Decay

Based on Ebbinghaus's forgetting curve, each memory gets a token budget tied to saliency. In the paper, lifespan is approximately Saliency × 4,000 tokens: low-saliency memories are deleted on expiry, while high-saliency memories are distilled and archived.

LIFESPAN ≈ saliency * 4000 tokens

IF budget_expires AND saliency <= 2:
  REMOVE(memory)

IF budget_expires AND saliency >= 4:
  ARCHIVE(DISTILL(memory))

IF memory_is_retrieved:
  RESET(decay_clock)

Opinionated Extraction

Rather than extracting atomic facts, Soul's prompt is written like a friend's inner monologue. It captures who someone is, not what they said, and emits add, edit, remove, and merge operations.

SYSTEM: Update memory like a close friend's inner monologue

1. WHO THEY ARE, not what they said
   Good: "she's seriously thinking about going back to school"
   Bad:  "she said she is applying to grad school"

2. OUTPUT OPS: add, edit, remove, merge

3. CONTENT: short, single-thought summary

4. CERTAINTY:
   "known"      = clear or repeated signal
   "hypothesis" = weak signal, must end with "?"

5. INCLUDE: reasoning + curious_about

6. NEW MEMORIES: typically 0-2 per 30-message window

Memory Stores

Soul retrieves from two stores. Active memories are the current user model and go directly into prompt context. Archived memories are distilled, embedded past knowledge that can be retrieved later when relevant.

Memory Retrieval

At query time, Soul retrieves from both stores. Active memories go straight into context, while archived memories are ranked by semantic relevance, saliency, and recency before they are surfaced.

FUNCTION retrieve(query, user_id):
  active = TOP(active_memories(user_id), 3) // direct prompt context

  query_embedding = embed(query)
  archived = cosine_similarity_search(
    query_embedding,
    archived_memories(user_id),
    limit = 5
  )

  ranked = rank(
    archived,
    by = semantic_relevance + saliency + recency
  )

  RETURN active + TOP(ranked, 5)

Reinforcement (Testing Effect)

Roediger & Karpicke (2006) showed that retrieval strengthens memory. In Soul, when a topic resurfaces and a related memory is retrieved, its decay clock resets. That is how sustained interests persist while one-off mentions fade.

Reinforcement comes from retrieval, not from keeping every weak signal forever. One-off mentions still fade if they are never brought back up.