The Three-Tier Memory System

Bastion implements a three-tier memory architecture inspired by cognitive science: working memory (STM), long-term memory (LTM), and forensic memory. Each tier serves a distinct purpose — fast retrieval, durable knowledge, and tamper-evident audit.

Tier 1 — Short-Term Memory (Working Cache)

The fastest tier. An in-memory LRU cache that holds recently and frequently accessed memories for sub-millisecond retrieval. When a memory is accessed 3+ times, it's automatically promoted from CockroachDB into the cache.

The MemoryRouter sits between the application and storage, transparently routing searches across both tiers:

from bastion.cache_router import MemoryRouter

router = MemoryRouter(
    memory=bastion_memory,
    cache_size=1000,           # L1 capacity
    promotion_threshold=3,     # accesses before L1 promotion
    demotion_interval_seconds=300,  # cold-check interval
)

# Search merges L1 + L2 results
results = router.search("deploy pipeline", k=5)

# Stats show cache hit rate
stats = router.get_stats()
# → {"cache_size": 42, "hit_rate_percent": 78.5, ...}

Tier 2 — Long-Term Memory (Persistent Store)

The durable backbone. Every memory is stored in CockroachDB with SERIALIZABLE isolation, a SHA-256 hash chain, and 1024-dim vector embeddings for semantic search.

Memory Types

Inspired by cognitive science, Bastion classifies memories into three types:

The LTM Gateway

The LTMMemoryGatewayis the "money shot" — before running an expensive workflow, it checks if a similar analysis already exists in long-term memory. If a match above the 80% similarity threshold exists, it returns the cached result instantly.

from bastion.ltm_gateway import LTMMemoryGateway

gateway = LTMMemoryGateway(memory_engine, reuse_threshold=0.80)

# Check before expensive workflow
result = gateway.check_reuse("analyze Q2 revenue trends")
if result:
    print(f"Found {result.similarity:.1%} match — reusing cached analysis")
    # Skip the full pipeline, return cached insight
else:
    analysis = run_expensive_workflow(...)
    gateway.store_analysis("analyze Q2 revenue trends", analysis)

Multi-Agent Merge (CRDT)

When multiple agents share a memory store, conflicts are resolved using CRDTs (Conflict-free Replicated Data Types) with three merge strategies:

Tier 3 — Forensic Memory (Audit & Compliance)

The tamper-evident layer. Every memory write appends to an immutable audit log with SHA-256 hash chaining. If any record is modified, the chain breaks — detected instantly by the forensic report.

Hash Chain Integrity

# Each memory block stores:
cryptographic_hash = SHA-256(content + previous_hash)
previous_hash      = SHA-256 of the last block

# Forensic verification (run via MCP tool):
SELECT memory_id, cryptographic_hash
FROM agent_audit
WHERE action = 'memory_store'
ORDER BY recorded_at ASC;

# If any record is modified:
#   Hash chain breaks → detected by forensic_report

Forensic Report

The forensic_report MCP tool queries live CockroachDB data to verify chain integrity, count audit entries, and check memory distribution — no mocks, real cluster queries:

AS OF SYSTEM TIME

CockroachDB's MVCC enables point-in-time queries — see exactly what your agent knew at any timestamp without maintaining separate snapshots:

-- What did the agent know on Jan 15, 2026 at noon?
SELECT content, importance_score, created_at
FROM agent_memory
AS OF SYSTEM TIME '2026-01-15T12:00:00Z'
WHERE agent_id = 'my-agent'
ORDER BY importance_score DESC
LIMIT 10;

Sleep-Time Consolidation (Dreaming)

When agents are idle, background processes review recent episodic memories and consolidate learnings into durable knowledge — inspired by how the human brain consolidates memories during sleep.

Consolidation is triggered by:

# Trigger consolidation manually
from bastion.dreaming import MemoryDreamer

dreamer = MemoryDreamer(memory_engine)
journal = dreamer.dream(agent_id="my-agent")

print(f"Consolidated {journal.memories_consolidated} memories")
print(f"Promoted {journal.memories_promoted} episodic → semantic")
print(f"Pruned {journal.memories_pruned} low-value memories")
print(f"Duration: {journal.duration_ms:.0f}ms"

Contradiction Detection

When a new memory is stored, Bastion scans existing memories for contradictions across three dimensions:

Drift Detection

The MemoryDriftmodule monitors behavioral drift across five dimensions — detecting when an agent's behavior changes unexpectedly over time: