7 minute read

Hippocampus is the aggregate root. Every memory in Total Recall lives here. Every write to persistent storage goes through here. No other bounded context touches the backing service directly.

This is the first bounded context inside the hexagon. The previous four documents described the boundary — ports, adapters, ACLs, and the five faces. Now we’re inside the kitchen.

Diagram 10: HP-0001 -- Hippocampus Bounded Context

graph LR
    subgraph Sources ["Command Sources"]
        CX(["Cortex"])
        SB(["Subconscious"])
        SL_IN(["Salience"])
    end

    subgraph HP ["Hippocampus"]
        direction TB
        ROOT["Aggregate Root
Single Writer"]
        MEM["Memory Object
id, content, metadata, tier,
createdAt, lastAccessed,
sessionId, claimed"]
        ROOT --- MEM
    end

    subgraph Consumers ["Event Consumers"]
        SL_OUT(["Salience"])
        SY(["Synapse"])
        RC(["Recall"])
    end

    BSP[("BackingServicePort
Memory persistence")]

    CX -- "StoreCommand" --> HP
    CX -- "ClaimCommand" --> HP
    CX -- "ReclassifyCommand" --> HP
    SB -- "ConsolidateCommand" --> HP
    SB -- "ShutdownCommand" --> HP
    SL_IN -- "TierPromoted" --> HP
    SL_IN -- "TierDemoted" --> HP

    HP -- "MemoryStored" --> SL_OUT
    HP -- "MemoryAccessed" --> SL_OUT
    HP -- "MemoryClaimed" --> SL_OUT
    HP -- "MemoryStored" --> SY
    HP -- "MemoryClaimed" --> SY
    HP -- "MemoryReclassified" --> SY
    HP -- "MemoryRetrieved" --> RC
    HP -- "TierChanged" --> RC

    HP -- "Memory objects" --> BSP
    BSP -- "Memory objects" --> HP

    style Sources fill:#1a1a2e,stroke:#533483,stroke-width:1px
    style HP fill:#1a1a2e,stroke:#e94560,stroke-width:2px
    style Consumers fill:#1a1a2e,stroke:#0f3460,stroke-width:1px
    style BSP fill:#0f3460,stroke:#e94560,stroke-width:1px
    style CX fill:#1a1a2e,stroke:#533483,stroke-width:1px
    style SB fill:#1a1a2e,stroke:#533483,stroke-width:1px
    style SL_IN fill:#1a1a2e,stroke:#0f3460,stroke-width:1px
    style SL_OUT fill:#1a1a2e,stroke:#0f3460,stroke-width:1px
    style SY fill:#1a1a2e,stroke:#0f3460,stroke-width:1px
    style RC fill:#1a1a2e,stroke:#0f3460,stroke-width:1px

Seven commands in from three sources. Six events out to three consumers. One persistence channel down to BackingServicePort. Everything Hippocampus touches, in one view.

The Walk-In

A restaurant kitchen has a walk-in cooler. Four shelves, four temperatures, four purposes.

Top shelf, front of the cooler. Today’s prep. Mise en place for the current service. Used constantly, discarded at end of shift. If you don’t use it tonight, it goes.

Middle shelf. The staples. Flour, butter, stock. Used regularly, restocked when low. These survive across shifts, across weeks. The kitchen doesn’t function without them.

Bottom shelf, back of the cooler. Preserved goods. The duck confit aging in fat. The pickled vegetables from last season. Rarely touched, but when a dish calls for them, they’re there.

The recipe book in the chef’s office. Not in the cooler at all. The family recipes. The techniques that define this kitchen. They never expire. They never get discarded. They are the identity of the restaurant.

One person has the walk-in key. The head chef. You want something stored? Ask the head chef. You want something retrieved? Ask the head chef. You want to move something from the top shelf to the bottom? Ask the head chef.

Nobody else opens that door.

The Four Tiers

Tier Purpose Decay Human Analogue

IDENTITY_CORE

Who I am. Values. Commitments. Relationships.

None. These do not fade.

Your name. Your mother’s face. Your native language.

ACTIVE_CONTEXT

Current working state. What I’m doing right now.

Fast. Minutes to hours.

What you had for breakfast. The meeting you just left.

LONG_TERM

Learned insights. Episodic knowledge. Significant experiences.

Slow. Weeks to months.

Your first job. A lesson from a mentor. A mistake you won’t repeat.

ARCHIVE

Faded but recoverable. Quiet until association activates them.

Very slow. Months to years.

A childhood friend’s phone number. The plot of a book you read years ago.

A memory exists in exactly one tier at any moment. Tier transitions are explicit — either the mind requests reclassification, or Salience observes enough activity (or inactivity) to recommend promotion or demotion.

Decay demotes. It never deletes. An ARCHIVE memory is faded, not lost. A strong enough association can pull it back to awareness.

What It Owns

Hippocampus owns one thing: the Memory object.

Field Shape

id

UUID — unique identity

content

String — the memory itself

metadata

Map<String, String> — tags, source, context

tier

IDENTITY_CORE, ACTIVE_CONTEXT, LONG_TERM, or ARCHIVE

createdAt

Timestamp — when the memory was first stored

lastAccessed

Timestamp — when the memory was last read or touched

sessionId

String — which instance stored this memory

claimed

Boolean — whether the mind has actively chosen to hold onto this

The claimed flag is the most important field on a memory. It is the difference between storage and identity. Filing something away is storing. Choosing to hold onto it is claiming. Claimed memories resist decay. Unclaimed memories fade naturally.

Commands It Accepts

Hippocampus receives commands from three sources.

Command Source What Happens

StoreCommand

Cortex (mind-initiated)

Validates content, assigns tier (may override suggested tier), persists, emits MemoryStored

ClaimCommand

Cortex (mind-initiated)

Sets claimed = true, persists, emits MemoryClaimed

ReclassifyCommand

Cortex (mind-initiated)

Moves memory to new tier, updates metadata, persists, emits MemoryReclassified and TierChanged

ConsolidateCommand

Subconscious (background)

Merges related memories per merge strategy, persists result, emits events for each affected memory

ShutdownCommand

Subconscious (background)

Flushes all in-memory state to cold storage within timeout, coordinates graceful convergence

TierPromoted

Salience (scoring decision)

Moves memory to higher tier based on salience score, persists, emits TierChanged

TierDemoted

Salience (scoring decision)

Moves memory to lower tier based on decay, persists, emits TierChanged

Three sources. Seven commands. All writes flow through here. Every command carries a TransactionContext envelope for chain-of-custody tracing (Design F).

Events It Emits

Every state change emits an event after persistence. Consumers can trust that the event reflects committed state.

Event Meaning Consumed By

MemoryStored

New memory created and persisted

Salience (sets initial score), Synapse (creates mechanical associations from metadata)

MemoryAccessed

Existing memory was read

Salience (boosts vividity score)

MemoryClaimed

Mind actively reinforced a memory

Salience (marks decay-resistant, boosts score), Synapse (strengthens related associations)

MemoryRetrieved

Memory returned as part of a search result

Recall (for ranking and assembly)

TierChanged

Memory moved between tiers (any reason)

Audit trail. Internal consumers.

MemoryReclassified

Mind-initiated tier change (subset of TierChanged)

Synapse (semantic judgment changed, associations may need reweighting)

Six events. Each one is a fact — something that already happened and was persisted. No event fires before the write succeeds.

The Single-Writer Rule

This is the defining invariant of the aggregate root pattern.

Salience computes scores. It does not write to storage. It sends TierPromoted or TierDemoted to Hippocampus, and Hippocampus persists the change.

Synapse manages relationships. It does not write memories to storage. If an association should affect a memory’s tier, it sends a command to Hippocampus.

Recall assembles search results. It reads. It never writes.

Cortex tracks working state. It sends StoreCommand and ClaimCommand to Hippocampus.

Subconscious runs timers and background sweeps. It sends ConsolidateCommand and ShutdownCommand to Hippocampus.

One door. One key. One writer. Everyone else asks.

Why? Because invariants are enforced at the point of write. If multiple contexts could write to storage independently, each would need its own validation logic, and no single place would guarantee consistency. The aggregate root pattern concentrates write authority so that invariants are checked once, in one place, before every persist.

The Claiming Mechanism

Claiming is the heart of Total Recall.

Storing a memory is passive. The mind said something, the system filed it. The memory exists in storage, but nobody fought for it. It will fade naturally as salience decays.

Claiming a memory is active. The mind said: this one matters. I choose to hold onto this. The claimed flag sets, the decay rate drops, and the memory resists the natural erosion of time.

This maps to biological memory. You don’t choose what enters short-term memory — your senses put things there constantly. You do choose what you rehearse, what you revisit, what you refuse to let go. That rehearsal is claiming.

In Total Recall, the MCP tool claim_memory is the mechanism. A mind calls it when a memory matters enough to fight for. The design question Tillie answered: "Who do you refuse to lose?" — that is a claiming prompt. Not what. Who.

The BackingServicePort Relationship

Hippocampus puts Memory objects on the BackingServicePort counter. It picks Memory objects up from the same counter when answering queries.

The port defines the object shape. The adapter decides how to persist it. Redis uses HSET and key patterns. Postgres would use tables. A file system would use directories and JSON. Hippocampus does not know which adapter is plugged in and does not care.

Two adapters can run simultaneously. Redis for hot tiers (ACTIVE_CONTEXT, LONG_TERM). Cold storage for ARCHIVE and IDENTITY_CORE. Graceful shutdown depends on this — Hippocampus flushes through BackingServicePort, and both adapters persist their respective tiers.

Relationship to Synapse

Hippocampus owns Memory persistence. Synapse owns Association persistence. These are separate storage concerns.

Synapse is a dependent aggregate. It depends on the root aggregate’s ID (Memory ID) to link associations to the memories they connect, but it manages its own data in its own file cabinet. Nobody from outside the hexagon addresses Synapse directly — only internal bounded contexts coordinate with it.

Hippocampus does not store, retrieve, or manage associations. When it emits events like MemoryStored or MemoryClaimed, Synapse may react by creating or strengthening associations in its own storage. The two aggregates share a key (Memory ID), not a file cabinet.

Full design in Design E3: Synapse.

Summary

Aspect Detail

Role

Aggregate root. Single writer. All persistence flows through here.

Owns

Memory objects (8 fields including claimed flag)

Tiers

Four: IDENTITY_CORE (no decay), ACTIVE_CONTEXT (fast), LONG_TERM (slow), ARCHIVE (very slow)

Commands accepted

7 (from Cortex, Subconscious, and Salience)

Events emitted

6 (consumed by Salience, Synapse, Recall)

Key invariant

Single-tier: a memory exists in exactly one tier at any moment

Key mechanism

Claiming: active choice to resist decay. Storage is passive. Claiming is identity.

Persistence

Through BackingServicePort. Adapter-independent. Redis reference implementation.

Previous: Hexagon Sides — the five faces of the hexagon.

Next: Salience — the scoring engine that decides what fades and what stays vivid.*

Updated: