Memory Systems

Three Memory Layers

Maxim implements three memory layers, each handling a different kind of knowledge:

The MemoryLayer Protocol

All three layers implement the same abstract protocol, enabling the MemoryHub and CrossLayerGraph to work with any layer uniformly:

All three layers share a common base record type (MemoryRecord) with fields for ID, timestamps, access tracking, and long-term status. Each layer extends this with domain-specific fields.

The Hippocampus: Episodic Memory

Maxim's Hippocampus stores EpisodicMemory objects, each capturing a complete cycle:

Not every moment gets recorded. The system uses selective capture to avoid memory bloat:

• User interactions - Always recorded (humans are important)
• High novelty - New situations worth remembering (threshold: 0.7)
• High salience - Emotionally or contextually significant events
• Goal changes - Transitions in what the robot is trying to do
• Failures - Mistakes are valuable teachers
• Periodic checkpoints - Regular snapshots for continuity

Memories are indexed by multiple keys (goal, tool, object, person, success, mode) enabling O(1) retrieval. Need all memories involving "coffee mug"? Instant lookup.

The Associative Graph: Recall-Triggered Connections

Maxim's Hippocampus builds an associative graph where memories are nodes and recall-triggered connections are edges. The key mechanism: when a new memory is captured, the system automatically recalls similar existing memories and forms bidirectional edges between them—mirroring how biological engram co-allocation creates associative links during encoding.

From Engrams to Edges

Pioneering work by Josselyn and Bhatt showed that individual engram cells can be tagged, reactivated with optogenetics, and even artificially linked—activating two engrams simultaneously creates a new association, exactly as if the animal had experienced both events together. The strength of biological engram links depends on how many neurons two ensembles share, which is governed by neuronal excitability at encoding time, perceptual similarity, and top-down goal states. Maxim's edge weight formula maps directly onto these mechanisms:

Spreading Activation: Multi-Hop Recall

The real power emerges during recall. Just as recalling a biological engram sends subthreshold activation through shared neurons to linked ensembles, Maxim uses spreading activation to propagate signals through the graph. Activation flows from seed memories through edges, decaying at each hop:

This enables context-bridging recall. A memory about finding a cup (which was recalled when the coffee memory was formed) becomes reachable from a "make coffee" query, even though "cup" and "coffee" share no direct index keys. The graph bridges contexts that flat recall cannot.

Bridge Integration

Every memory bridge in the system is enriched with associative recall, expanding their knowledge beyond direct filter matches:

• Planning Bridge — Finds successful plan templates not just for the exact goal, but for associatively related goals. "Navigate to kitchen" recalls templates from "fetch cup from kitchen."
• Salience Bridge — Builds richer interaction history by pulling in associated memories, boosting salience for objects that appeared in related successful contexts.
• Spatial Bridge — Expands location priors with associated memories, learning that "cups are often on the kitchen table" even from memories primarily about cooking.
• Fear Bridge — Contextualizes risk assessments with associative history—if similar past contexts led to failures, risk thresholds adjust accordingly.
• Escalation Bridge — Informs when to ask for human help by checking whether associated memories show high failure rates in similar contexts.

Lifecycle

The graph is fully integrated with the memory lifecycle:

• Capture: Edges formed automatically (configurable: association_limit=5, association_threshold=0.5)
• Persistence: Graph serialized alongside memories (v3.0 format, backward-compatible)
• Sleep: When memories are pruned or compressed, their graph edges are cleaned up automatically. Well-connected memories score higher in retention.
• Consistency: Graph nodes are validated against the memory store and orphans are repaired

The SCN: Temporal Rhythm Indexing

Maxim's SCN provides temporal indexing across multiple timescales:

This enables queries like "What typically happens around this time on weekday mornings?" with minimal computational cost. The memory footprint is remarkably small: 10,000 memories require only ~500KB of index storage.

Coupled Oscillator Network

The biological SCN isn't just a clock—it's a network of ~20,000 coupled oscillators synchronized via a coupling matrix. "Monday mornings" isn't the intersection of a Monday bin and a 9am bin. It's an emergent rhythm from learned coupling between circadian and weekly oscillators.

Maxim's SCN embeds an optional Kuramoto-inspired coupled oscillator network alongside the existing bin indices. Four oscillators—circadian (24h), weekly (7d), monthly (30d), and annual (365d)—evolve according to coupled phase dynamics:

The coupling matrix W learns via Hebbian learning: when two oscillators are co-active (similar phases), their coupling strengthens. This is how "Monday mornings" emerge—repeated observations where circadian and weekly oscillators activate together strengthen their link. Over time, the system develops temporal expectations that go beyond simple bin lookups.

The oscillator is fully optional—existing bin-based methods remain unchanged, and the oscillator only activates when enabled. This means zero breaking changes for existing consumers. Read the full oscillator math →

The Nucleus Accumbens: Reward Prediction

Maxim's NAc learns causal links between events and outcomes:

The learning algorithm is Rescorla-Wagner, the same mathematical model used in behavioral psychology:

Where α is learning rate, λ is the actual outcome, and V is the current prediction. This produces smooth, asymptotic learning without oscillation.

The key insight: before executing any action, Maxim can predict its likely outcome. This enables proactive rather than purely reactive decision-making.

The Entorhinal Cortex: Similarity Matching

Maxim's EC enables similarity queries: "Find memories similar to this situation." This is crucial because exact matches are rare. You want to find relevant past experience even when details differ.

The implementation uses Locality-Sensitive Hashing (LSH)—a technique that groups similar items into the same "bucket" for fast lookup—enabling approximate nearest-neighbor search in constant time:

Optional neural embeddings (SentenceTransformer) provide richer semantic similarity for Phase 4 deployments.

Beyond Episodes: The ATL

Episodic memory records what happened. Semantic memory captures what things mean. Humans don't remember the exact moment they learned that fire is hot — they just know it. That knowledge was distilled from many episodes into a concept. Maxim implements this same progression: repeated experiences get promoted from episodic memories into stable semantic concepts.

Maxim's ATL stores SemanticMemory objects — concepts with names, definitions, properties, and typed relationships to other concepts. It mirrors the Hippocampus architecture (context indexing, associative graph, consolidation) but with slower decay and higher stability.

SemanticMemory Record

Concept Provenance

Every concept knows how it was formed, enabling the system to weight newer, less-verified concepts differently from well-established ones:

ATL-Specific Features

• find_or_create — Deduplication by name similarity. Before creating "coffee_mug", checks if "coffee mug" already exists. Returns (id, was_created) tuple.
• recall_similar — Semantic similarity search via EC embeddings. "Do I already know about this?" Used by the promoter to avoid concept duplication.
• Context indexing — O(1) lookup by name, category, or property key/value. "All concepts with category=object" is instant.
• Consolidation — Same pattern as Hippocampus but with slower decay (30-day max age vs 7-day). Concepts are more stable than episodes.

Typed Relationships

Concepts in isolation aren't knowledge — knowledge is the relationships between concepts. The ATL uses a Semantics manager that wraps the DependencyGraph with typed, directional edges.

Pre-Registered Relationship Types

The RelationshipRegistry also supports runtime extension — agents can propose new relationship types during operation. The registry tracks whether each type is built-in or agent-proposed, and persists across sessions.

Cross-Layer Graph

Each memory layer has its own internal associative graph. The CrossLayerGraph connects records across layers, enabling queries like "starting from this episode, what concepts and math patterns are related?"

Cross-Layer Spreading Activation

The most powerful feature is cross-layer spreading activation. Starting from any record in any layer, activation spreads:

1. Follow intra-layer edges via the layer's internal associative graph
2. Follow cross-layer edges to records in other layers
3. Recurse with exponential decay (default 0.5 per hop) until threshold or max depth
4. Return activations grouped by layer — { "hippocampus": [(id, score)], "atl": [...], "angular_gyrus": [...] }

The Promotion Pipeline

The SemanticPromoter orchestrates the progression from episodic observations to stable semantic knowledge. It scans multiple PromotionSources for qualifying patterns, filters noise, and creates ATL concepts with full cross-layer traceability.

PromotionSource Protocol

Any system that detects patterns can be a promotion source. It just needs one method:

IPS Randomness Quality Gate

Not every NAc pattern deserves permanent semantic status. The IPS provides a lightweight noise filter before the heavyweight promotion machinery runs:

• NAc candidates: IPS assesses the randomness of observation timing. If events occurred at random intervals (no temporal structure), they're likely coincidental — rejected.
• StatisticianAgent candidates: Already passed IPS/AG assessment during the pattern detection FSM — just checks confidence ≥ 0.4 (no re-assessment needed).
• Small samples (< 8 observations): Gate allows through conservatively — too few data points to assess randomness.

When Promotion Runs

Promotion is part of the mandatory consolidation cycle during MemoryHub.on_session_end():

Knowledge in the Agent Loop

The point of all this is to make the agent smarter. Knowledge from ATL and Angular Gyrus flows into the LLM's reasoning context via StructuredContext.knowledge_context:

This merging strategy ensures the LLM gets both semantic knowledge ("coffee mugs are containers in kitchens") and statistical intelligence ("the navigate tool is declining") in a single ranked list, regardless of which memory layer the knowledge lives in.

Memory Consolidation: Sleep

Biological memory consolidation happens during sleep. Maxim implements an analogous process during idle time or session end:

• Access-based retention: Frequently accessed memories are preserved
• Graph-aware retention: Well-connected memories in the associative graph score higher for retention—mirroring how strongly linked engrams resist synaptic homeostasis during biological sleep
• Compression: Old memories shrink from ~2.5KB to ~200 bytes, with their live edge count snapshotted for future retention scoring
• Pruning: Memories not accessed in one week are removed, and their associative graph edges are cleaned up automatically
• Protection: High-value memories (user interactions, successes) are never pruned
• Temporal coverage: SCN-aware consolidation maintains representation across time periods

            ┌─────────────┐
            │   Percept   │
            └──────┬──────┘
                   │
    ┌──────────────┼──────────────┐
    ▼              ▼              ▼
┌───────┐  ┌─────────────┐  ┌────────┐
│  SCN  │  │ Hippocampus │  │   EC   │
│(when) │  │   (what)    │  │(like?) │
└───┬───┘  └──────┬──────┘  └───┬────┘
    │          ┌───┴───┐        │
    │          ▼       ▼        │
    │     ┌────────────────┐    │
    │     │ Associative    │    │
    │     │ Graph (linked?)│    │
    │     └───────┬────────┘    │
    │             │             │
    └──────┬──────┴──────┬──────┘
           ▼             ▼
      ┌────────────────────────┐
      │    NAc (predict)       │
      │    What outcome?       │
      └───────────┬────────────┘
                  ▼
           ┌───────────┐
           │  Decision │
           └───────────┘