Four Memory Tiers¶

The 4-Tier Architecture¶

Memory is not an undifferentiated flat vector store. As formalized in the Memory Fundamentals Specification (MF-001), distinct memory tiers address distinct operational retention windows, access frequencies, and consolidation dynamics without asserting biological substrate identity. Spector implements this model with four canonical memory tiers backed by the off-heap Memory Kernel:

graph TB
    subgraph "Engram Dispatcher (Memory Kernel)"
        direction TB
        DISP["EngramMemory Shape Accessor<br/><i>Polymorphic dispatch over MemoryType</i>"]
    end

    DISP --> WM["🧪 Working Memory<br/>Prefrontal Cortex<br/>━━━━━━━━━━━━━━━━━<br/>Volatile circular buffer<br/>~100 records<br/>runtime.bundle"]
    DISP --> EM["📝 Episodic Memory<br/>Hippocampus<br/>━━━━━━━━━━━━━━━━━<br/>Time-partitioned bundles<br/>Empirical scale: 10M engrams<br/>partition.bundle"]
    DISP --> SE["🧬 Semantic Memory<br/>Neocortex<br/>━━━━━━━━━━━━━━━━━<br/>Crystallized knowledge<br/>Permanent storage<br/>partition.bundle"]
    DISP --> PR["⚙️ Procedural Memory<br/>Basal Ganglia<br/>━━━━━━━━━━━━━━━━━<br/>Learned rules & skills<br/>High persistence<br/>partition.bundle"]

Tier Dispatch & Kernel Backing¶

All four memory stores are backed directly by the off-heap spector-kernel:

• Working Memory: Hosted in runtime.bundle as a contiguous circular buffer for active working context.
• Episodic, Semantic, and Procedural Memories: Hosted in sequential partition bundles (partitions/{seq}/partition.bundle) with dedicated 96-byte strength regions (RegionId.STRENGTH).
• Engram Storage: All tiers utilize the unified 64-byte pure encoding header with 128-bit Synaptic Bloom tags for fast candidate pre-screening.

🧪 Working Memory (Prefrontal Cortex)¶

Design rationale: Working memory maintains a limited workspace for active processing and immediate task execution. It holds transient context in biological systems (\(7 \pm 2\) chunks).

Working memory operates as a high-speed circular buffer: when the allocated capacity is reached, new memories overwrite the oldest records. This provides low latency for active dialogue without bloating long-term indexes.

Synaptic Tag Pre-Screening: Working Memory supports sub-microsecond candidate filtering via the 128-bit Synaptic Bloom filter, enabling instant tag lookups prior to dense vector calculation.

📝 Episodic Memory (Hippocampus)¶

Design rationale: Episodic memory encodes autobiographical events as time-ordered traces. Events are appended rapidly (one-trial learning), and during consolidation phases, the hippocampus replays sequences for transfer into permanent cortical memory.

Partition Lifecycle¶

Episodic memory partitions progress through a structured lifecycle:

stateDiagram-v2
    [*] --> ACTIVE: Open new partition bundle
    ACTIVE --> SEALED: Capacity reached (10K engrams)
    SEALED --> CONSOLIDATING: Sleep consolidation daemon triggered
    CONSOLIDATING --> CRYSTALLIZED: Knowledge centroids promoted to Semantic
    CRYSTALLIZED --> ARCHIVED: Sealed historical partition
    ARCHIVED --> [*]

1. Active: The current partition accepts sequential appends via the Write-Ahead Log.
2. Sealed: When the partition capacity threshold is reached, it is sealed as read-only, and the next partition is initialized.
3. Consolidating: The background consolidation daemon replays related episodic events, identifying common patterns.
4. Crystallized: Abstracted centroids are promoted to the permanent Semantic tier.

🧬 Semantic Memory (Neocortex)¶

Design rationale: Semantic memory stores distilled, permanent world knowledge — generalized concepts, domain facts, and rules extracted from repeated experience.

Semantic Memory Creation¶

Semantic memories enter the system through two primary pathways:

1. Remember Pathway: Client applications directly store verified facts into the semantic tier (tier: SEMANTIC).
2. Reflect Pathway (Sleep Consolidation): The hippocampal sleep consolidation engine analyzes clusters of repeated episodic memories, synthesizes generalized summaries, and promotes them to permanent semantic engrams.

⚙️ Procedural Memory (Basal Ganglia)¶

Design rationale: Procedural memory stores learned behavioral patterns, motor routines, and procedural protocols — operational skills that execute automatically.

Procedural memories represent actionable operational rules. Because procedural rules guide agent decisions under uncertainty, they possess higher baseline importance scores and resist temporal decay.

Client SDK Usage¶

Client applications can target specific tiers or allow cognitive routing:

from spector_client import SpectorClient, MemoryTier

client = SpectorClient.builder().with_rest("http://localhost:7070").build()

# Store in Semantic Memory
client.memory.remember(
    text="The client application utilizes OAuth 2.0 PKCE authentication",
    tier=MemoryTier.SEMANTIC,
    tags=["auth", "security"],
    interest=0.9,
)

import { SpectorClient, MemoryTier } from '@spectrayan/spector-client';

const client = SpectorClient.createDefault('http://localhost:7070');

// Store in Semantic Memory
await client.memory.remember({
  text: 'The client application utilizes OAuth 2.0 PKCE authentication',
  tier: MemoryTier.SEMANTIC,
  tags: ['auth', 'security'],
  interest: 0.9,
});

import com.spectrayan.spector.client.SpectorClient;
import java.util.List;

try (var client = SpectorClient.builder().baseUri("http://localhost:7070").build()) {
    client.memory().remember(
        "The client application utilizes OAuth 2.0 PKCE authentication",
        "SEMANTIC",
        List.of("auth", "security")
    );
}

curl -X POST http://localhost:7070/api/v1/memory/remember \
  -H "Content-Type: application/json" \
  -d '{
    "text": "The client application utilizes OAuth 2.0 PKCE authentication",
    "tier": "SEMANTIC",
    "tags": "auth,security",
    "interest": 0.9
  }'

Next Steps¶

• The 6-Phase Scoring Pipeline — associative multi-tier retrieval
• Synapse — Tags & Scoring — 128-bit Bloom filters and affective tagging
• Hippocampus — Sleep Consolidation — episodic to semantic transfer
• Memory Kernel — off-heap storage and bundle containers