Soul Memory Architecture: Episodic, Semantic, Procedural

OpenClaw's memory model maps to a distinction cognitive scientists have been making for decades, and that Letta, MemGPT, and Open Souls all reach for in their own vocabulary. A Soul has three memory layers: episodic (what happened), semantic (what's true), and procedural (how it works). Each store has a different write policy, a different recall trigger, and a different retention curve. Conflating them is why so many agent demos look impressive on day one and feel amnesiac on day twenty.

Episodic — the Soul's diary

Episodic memory is a stream of events: 'Tuesday 3pm: Maya asked Atlas to draft the postmortem for incident-204. Atlas drafted three sections, Maya rewrote the timeline, the doc shipped at 4:15.' Each entry is small, dated, and embedded in a vector store so the runtime can pull semantically related episodes back when relevant input shows up.

• Write trigger: end of every meaningful turn — a turn that changed state, learned a fact, or completed a task
• Recall trigger: vector similarity to current input, weighted by recency (last 7 days outweigh last 7 months)
• Decay: episodes older than N days drop out of recall unless they get promoted to semantic memory
• Anti-pattern: storing every chat turn — the store fills with noise, recall starts pulling irrelevant chitchat

Semantic — the Soul's beliefs

Semantic memory is the Soul's stable picture of the world: 'Maya is a senior SRE on the platform team. The Tendril production database is Postgres 16 on RDS. Postmortems ship within 48 hours.' These are facts, not events — they don't get a timestamp, they get edited when wrong.

• Write trigger: explicit confirmation ('yes, that's right'), explicit correction ('actually, it's Postgres 16'), or repeated observation across episodes
• Recall trigger: keyword / symbolic lookup, often by entity (the Soul recalls 'what I know about Maya' not 'episodes near Maya')
• Retention: long-lived; updated in place when superseded, archived when contradicted
• Anti-pattern: pushing every episodic detail in here — semantic memory bloats and starts contradicting itself

Procedural — the Soul's muscle memory

Procedural memory is how the Soul does things — the saved workflow for 'draft a postmortem,' the 12-step deploy ritual, the macro for triaging a Sentry alert. Procedural memory is what makes a senior agent feel senior: not that it knows more, but that it has stable ways of working.

• Write trigger: a workflow stabilizes — three successful runs of the same task pattern, or an explicit 'save this as a procedure'
• Recall trigger: task classification — when current request matches a known task class, load the procedure
• Versioning: procedures get version numbers; old versions are kept until the new one ships clean for N runs
• Anti-pattern: hardcoding procedures into the system prompt — they balloon the prompt and can't be edited without redeploy

The write-vs-recall imbalance

Most teams over-engineer the recall side and under-engineer the write side. They build elegant vector search, then write everything indiscriminately and choke the store with noise. Recall is mostly solved infrastructure. Write policy is where the Soul earns or loses its memory. Be picky about what goes in.

// A small write-policy helper for an OpenClaw Soul.
// The runtime calls this after every turn; you decide what to keep.

export function decideWrites(turn: Turn, soul: SoulCtx) {
  const writes: MemoryWrite[] = [];

  // Episodic — only if the turn changed state.
  if (turn.toolCalls.length > 0 || turn.factsConfirmed > 0) {
    writes.push({
      store: 'episodic',
      payload: {
        ts: turn.endedAt,
        actor: turn.userId,
        summary: turn.summary,         // 1-2 sentences max
        tags: turn.entities,
      },
    });
  }

  // Semantic — only on confirmed/corrected facts.
  for (const fact of turn.confirmedFacts) {
    writes.push({
      store: 'semantic',
      key: fact.entity + ':' + fact.attribute,
      payload: { value: fact.value, source: turn.id },
    });
  }

  // Procedural — only when a workflow stabilizes.
  if (turn.workflowOutcome === 'stable-third-success') {
    writes.push({
      store: 'procedural',
      payload: {
        taskClass: turn.taskClass,
        steps: turn.steps,
        version: soul.nextProceduralVersion(turn.taskClass),
      },
    });
  }

  return writes;
}

Apply: classify ten memories

1. 1Open a recent agent transcript with at least ten distinct exchanges
2. 2For each exchange, decide which memory store should keep it (episodic, semantic, procedural, or nothing)
3. 3Tally: if more than ~60% landed in one store, your write policy is unbalanced
4. 4Look at the 'nothing' bucket — those are the noise you should keep filtering out
5. 5Update your Soul's writePolicy fixture so the next agent run mirrors your manual classification

The big idea: episodic remembers what happened, semantic remembers what's true, procedural remembers how things are done. Three different stores, three different write policies, one Soul that actually feels like it remembers you.