Memory Systems

Three Memory Layers

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

All three layers implement the same abstract MemoryLayer protocol, so the MemoryHub and the cross-layer graph can work with any layer uniformly and every record knows how to describe itself to the LLM; the protocol and record fields are documented under Memory & consolidation on pymaxim.bio.

Staged Memory Formation

The MemoryAgent implements a staged formation pipeline. Rather than capturing memories immediately, observations progress through tiers before reaching the Hippocampus for permanent storage: forming, still accumulating context and protected from eviction during the active session; short-term, committed to the Hippocampus and subject to consolidation during sleep; and long-term, having survived consolidation waves.

While observations are forming, each one is wrapped in a container that tracks how important, how fresh, and how relevant it is, independently of the memory record itself. The ATL can also inject predicted outcomes into forming memories before they're committed, letting the system pre-fill expectations like "last time I saw this, X happened"—that mechanism is pattern completion, described below.

The Hippocampus: Episodic Memory

Maxim's Hippocampus stores EpisodicMemory objects, each capturing a complete cycle: perception, decision, action, outcome. 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
• 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. Capture rules and the record format are documented under Hippocampus on pymaxim.bio.

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: pattern overlap becomes shared detected objects and people between two memories (the largest share of the weight); goal-state modulation becomes matching or overlapping active goals; and co-allocation becomes closer in time = stronger link, decaying over hours. Synaptic homeostasis has its analogue too: sleep prunes weakly connected memories while well-linked ones score higher in retention.

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, decaying at each hop. A query for "make coffee" directly recalls "made coffee at 9am yesterday"; that memory's edge leads to "found cup on kitchen table", which in turn leads to "cleaned kitchen table last week"—two hops away from "coffee", but still contextually relevant. This is context-bridging recall: the cup memory 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.

Every memory bridge in the system is enriched with this associative recall: the Planning Bridge finds plan templates for associatively related goals ("navigate to kitchen" recalls templates from "fetch cup from kitchen"), the Spatial Bridge learns that "cups are often on the kitchen table" even from memories primarily about cooking, and the Fear and Escalation Bridges adjust their thresholds when associated memories show failures in similar contexts.

The SCN: Temporal Rhythm Indexing

Maxim's SCN provides temporal indexing across multiple timescales—hourly, daily, weekly, and monthly bins—so the system can answer "What usually happens at 9 AM?" or "What's different on Mondays?" with minimal computational cost and a remarkably small memory footprint.

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 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: predicting when patterns will recur and flagging temporally unusual events. Read the full oscillator math → Bin structure and configuration live under SCN on pymaxim.bio.

The Nucleus Accumbens: Reward Prediction

Maxim's NAc learns causal links between events and outcomes—an action like "internet_search" paired with a result like "success_with_results", each link carrying a valence, a strength, a confidence, and the context conditions under which it applies. 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 causal-link record and its parameters are documented under Nucleus accumbens on pymaxim.bio.

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—"find the red cup in the kitchen" should surface last week's "find the blue mug in the kitchen." 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 regardless of memory size; optional neural embeddings provide richer semantic similarity. Signature format and embedding options are documented under Entorhinal cortex on pymaxim.bio.

Semantic Memory: The Anterior Temporal Lobe

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.

The ATL as Semantic Hub

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. Before creating a concept the ATL checks whether a similarly named one already exists, and it can ask the EC "do I already know about this?" — which is how the promoter avoids concept duplication.

Every concept knows how it was formed, enabling the system to weight newer, less-verified concepts differently from well-established ones. The most common path is episodic consolidation: extracted from repeated episodes via NAc reward signals — "I've seen this pattern enough times to call it knowledge." Concepts can also arrive by agent inference, proposed by the StatisticianAgent from confirmed operational patterns; by direct ingestion from RAG or documents; or as a hybrid of both. Confidence grows with the number of episodes that reinforce a concept. The record format and consolidation settings are documented under Anterior temporal lobe on pymaxim.bio.

Concept Memory

The Concept class extends SemanticMemory with a set of memory references that track which records in each memory layer are associated with this concept — the Hippocampus episodes where a mug appeared, the Angular Gyrus record holding its salience statistics. This provides the backbone for concept extraction, grounding, pattern completion, and context building. References are capped with oldest-first eviction, and the ATL prunes low-confidence, stale concepts during consolidation the same way the Hippocampus prunes old episodes.

Concept Extraction

The ConceptExtractor runs as an async background worker that continuously transforms raw episodic memories into concept references. When the Hippocampus captures a new episode, the extractor queues it for processing on a dedicated thread — never blocking the agent's perception-decision-action loop. From each episode it pulls object and person names as concepts and tokenizes the goal string and tool name, so "navigate_to_kitchen" becomes the concepts "navigate" and "kitchen". Each term is found-or-created in the ATL, linked back to the episode, and reinforced.

Skills tap into the same pipeline. When a skill is active during memory formation, the extractor auto-creates a skill:<name> concept with EXECUTES_WITH edges to co-occurring concepts, so the system learns which concepts are relevant to which skills and can rank available skills against what it currently perceives. No hardcoded triggers — the ATL graph is the trigger system.

Concept Grounding

The ConceptGrounder transforms raw episodic references into statistical summaries stored in the Angular Gyrus. When a concept accumulates enough episode references, the grounder extracts numerical properties (salience, novelty, success rate) and runs them through the IPS→AG pipeline to produce math records — "mug salience: mean=0.78, std=0.12" — linked back to the concept with a QUANTIFIES edge in the cross-layer graph. When two concepts frequently appear in the same episodes, the grounder also strengthens the relationship between them via Jaccard similarity on their shared episode sets, creating or reinforcing a RELATED_TO edge with weight proportional to co-occurrence.

Concept-Aware Recall

The ConceptContextBuilder provides real-time concept context during the agent's perception-decision loop. When the agent sees objects, people, or pursues a goal, the builder finds matching ATL concepts and enriches them with relationship data and AG statistics — all within a configurable time budget. AG grounding can be expensive for concepts with many episodes, so the builder degrades gracefully: full context while budget allows, relationships plus cached AG records when it runs low, and name, category, and episode count when it's exhausted — still useful for basic context.

Pattern Completion

The PatternCompleter predicts likely outcomes for a partially-formed episode by traversing the concept graph. When a new episode is forming (has perception + context, but no decision/action/outcome yet), the completer chains: matching concepts → linked episodes → past outcomes. A forming episode that sees a mug under the goal "grasp_mug" matches the concepts mug and grasp, collects the past episodes they reference, and reads off what happened. Each prediction is traceable back to its source episode and, where the AG has grounded the concept, enriched with the relevant statistics.

The MemoryAgent calls the completer during the forming stage of memory formation, so the agent has predictions before it commits to a decision — the "last time I saw this, X happened" injection described under staged formation.

Relationships Within and Across Layers

Concepts in isolation aren't knowledge — knowledge is the relationships between concepts. The ATL wraps its graph with typed, directional edges: structural ones like IS_A ("coffee_mug" IS_A "container") and CAUSES; statistical ones like TRENDS_WITH, PHASE_LOCKED_TO, and PREDICTS ("morning_activity" PREDICTS "high_success"); and the learned EXECUTES_WITH edges from skill co-occurrence. Agents can propose new relationship types during operation, and the registry persists them across sessions.

Each memory layer has its own internal associative graph. The CrossLayerGraph connects records across layers — a concept is DERIVED_FROM the episodes that produced it, an Angular Gyrus pattern STATISTICALLY_CONFIRMS a concept — enabling queries like "starting from this episode, what concepts and math patterns are related?" The most powerful feature is cross-layer spreading activation: from any record in any layer, activation follows intra-layer edges, then cross-layer edges, recursing with exponential decay. From a Hippocampus episode where the navigate tool failed, activation finds similar failures, crosses to the ATL concept "navigate_tool_reliability", crosses again to the AG pattern showing the declining success rate, and finally reaches the record linking that decline to evening circadian phase.

Causal structure enters the hippocampal graph the same way. When a tool produces a surprising outcome (high reward prediction error), the system creates CAUSES edges connecting event episodes to outcome episodes, so recalling a past action activates its consequences. Tool errors route through the pain detector to the NAc as negative causal links, and tool events are temporally indexed by the SCN so time-based patterns (API rate limits, resource exhaustion) can be discovered.

The Promotion Pipeline

The SemanticPromoter orchestrates the progression from episodic observations to stable semantic knowledge. It scans multiple promotion sources for qualifying patterns, filters noise, and creates ATL concepts with full cross-layer traceability. Any system that detects patterns can be a promotion source. The promoter deduplicates candidates against what the ATL already knows, extracts the recurring elements, creates or reinforces the concept, forms relationships, and creates the cross-layer edges.

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. For NAc candidates it assesses the randomness of observation timing: if events occurred at random intervals (no temporal structure), they're likely coincidental — rejected. StatisticianAgent candidates have already passed IPS/AG assessment, so only a confidence check applies. Small samples are allowed through conservatively — too few data points to assess randomness.

When Promotion Runs

Promotion is part of the mandatory consolidation cycle at session end: the Hippocampus sleeps, the promoter runs, the ATL and Angular Gyrus consolidate (compress, decay, prune), and everything is persisted. The ordering is critical: promotion runs before consolidation so source episodes still exist when cross-layer edges form.

Knowledge in the Agent Loop

The point of all this is to make the agent smarter. Knowledge from the ATL and Angular Gyrus flows into the LLM's reasoning context via two channels in StructuredContext. The knowledge context merges ATL concepts and AG patterns via cross-layer spreading activation — broad, session-level knowledge ranked by relevance. The concept context is live output from the ConceptContextBuilder — percept-specific, only the concepts matching current objects, people, and goal, enriched with relationships and AG stats. Together, these give the LLM both broad knowledge ("the navigate tool is declining") and percept-specific concept context ("the mug I'm seeing has high success rate for grasping"), plus pattern completion predictions for what's likely to happen next.

Episode Valence & Affective Memory

Maxim annotates episodes, edges, and retrieval results with valence — a scalar measure of positive or negative affect derived from reactions that occurred during the episode. Each episode's valence is computed at finalization as the mean of all reaction valences received during its lifetime: pain reactions contribute negative values, success reactions positive values, and an episode with no reactions is neutral. An episode in which a sword shattered closes negatively valenced — future recall will carry the "this went badly" signal.

When episodes are linked by Hebbian edges in the associative graph, the edge inherits that valence, so the associative connections between memories carry emotional coloring — not just structural similarity. Spreading activation can propagate edge valence alongside activation strength during multi-hop recall, distinguishing positively and negatively valenced paths through the graph, and retrieval results come back annotated with their accumulated valence. The agent's prompt context includes this affective coloring — enabling reasoning like "I've done something similar before and it went badly" without requiring explicit causal chain reconstruction.

Reactions also reach the NAc, where they adjust per-node reward bias values in the Hebbian graph and modulate EC similarity thresholds: positive rewards raise the bias, which lowers the EC recognition threshold for rewarded nodes (the system becomes more permissive toward patterns it has been rewarded for). Negative or pain signals reduce bias toward zero but cannot invert it, so recognition returns toward the baseline threshold rather than narrowing below it.

Episode Boundaries

The Hippocampus must decide where one episode ends and the next begins. Rather than using a fixed timer, Maxim uses a set of boundary rules that trigger episode finalization based on contextual signals checked at each tick: too much time between events, a new input channel, an SCN temporal phase shift, and a pain spike. The first three handle temporal and contextual discontinuities. The last adds pain-driven episode boundaries:

Memory Consolidation: Sleep

Maxim implements a wave-based consolidation pipeline that separates staging from promotion, with path-dependent thresholds for one-shot learning (acute) and evidence-based learning (chronic). When an agent cycle completes, a significance score is computed from weighted heuristics—reward prediction error, user interaction, novelty, plan boundaries, extreme valence, energy change—and moments that score high enough are staged. During sleep, each staged moment is re-scored by a consolidation wave and either promoted into the Hippocampus, kept for another wave, or expired.

Staging Paths

Wave Scoring and Learnable Weights

Each consolidation wave re-evaluates staged moments against accumulated system evidence: the original significance score, whether the NAc has since corroborated the event→outcome pattern, whether the SCN has seen similar activity at similar times, whether similar percepts and contexts have recurred since staging, and whether something novel has become routine—which is exactly what's worth encoding.

The significance heuristic weights themselves learn from long-term utility. After a memory is promoted, the SignificanceWeightLearner tracks whether it becomes well-connected in the associative graph (indicating usefulness). Pearson correlation between heuristic scores and graph edge growth adjusts weights over time—heuristics that predict useful memories gain weight, others lose it. Thresholds, weights, and index capacities are documented under Memory & consolidation on pymaxim.bio.

Retention Principles

• Access-based retention: Frequently accessed memories are preserved
• Graph-aware retention: Well-connected memories score higher—mirroring how strongly linked engrams resist synaptic homeostasis during sleep
• Compression: Old memories shrink to a fraction of their size, with their edge count snapshotted for future retention scoring
• Pruning: Unaccessed memories are removed and their graph edges cleaned up
• 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?)│    │
    │     └───────┬────────┘    │
    │             │             │
    │    ┌────────┴────────┐    │
    │    ▼                 ▼    │
    │ ┌──────┐      ┌──────┐   │
    │ │ LSH  │      │ LSH  │   │
    │ │percep│      │contxt│   │
    │ └──┬───┘      └──┬───┘   │
    │    │              │      │
    └────┼──────┬───────┼──────┘
         ▼      ▼       ▼
    ┌────────────────────────┐
    │    NAc (predict)       │
    │    What outcome?       │
    └───────────┬────────────┘
                ▼
         ┌───────────┐
         │  Decision │
         └───────────┘