Memory Architecture

#Why Memory Is the Hard Problem

An agent fleet without persistent memory re-learns everything every session: past bugs, rejected designs, operational gotchas, the reason a config looks weird. Archon Merkaba treats memory as core infrastructure with the same reliability engineering as the trading system — because a memory system that silently fails is worse than none: you think you remembered.

#The Three Stores

1. Primary memory — a SQLite + vector-search store behind a background worker. Every session's observations (bugs fixed, decisions made, discoveries, gotchas) are captured automatically and are searchable semantically. It currently holds 20,000+ observations spanning the system's entire history.

2. Fleet mirror — a full-text-search database on the cloud plane, so cloud-side agents (scheduled jobs, chat-ops responders) can search the same institutional knowledge. A sync bridge runs at session start, moving new knowledge both directions.

3. Fallback store — a durable local SQLite written by a resilience layer whenever the primary's worker is offline. Reads fall back to querying the primary's on-disk database directly (which survives worker outages); writes are captured locally and flushed to the primary when it returns.

Alongside these, a file-based memory (plain markdown: one fact per file, with an index loaded into every session) holds the always-available core: standing rules, project state, key architectural summaries. Files need no worker, so this layer can never be "down."

#Token-Efficient Recall

Recall follows a strict three-layer funnel to avoid drowning sessions in context:

1. Search → compact index with IDs (~50–100 tokens per result)
2. Timeline → chronological context around interesting hits
3. Full fetch → complete details only for the filtered few (~500–1000 tokens each)

Fetching full details without filtering first is a protocol violation. Measured effect: roughly 10× token savings versus naive retrieval, and session-start context injection reports ~85% savings against raw replay.

#The Resilience Protocol

The memory layer's defining feature is that memory is never optional and never silently skipped. This is written policy, born from a real incident: during one long build session the memory worker was offline, and the session neither recalled context at start nor saved any of its work — an entire day of decisions effectively vanished. The postmortem produced:

• A resilience library (ResilientMemory): a pure-stdlib layer with save/search/flush/ status operations that works whether or not the worker is up.
• Session-start automation: sync and flush run automatically via hooks, so recovery from an outage requires no human memory.
• A one-line rule at the top of the policy file: worker down ≠ memory off.
• Behavior tests covering the offline-capture and flush paths.

Detection is explicit (health probes on the worker's local HTTP port, absence of the memory tools in-session), and the known failure modes — down to a "ghost socket" zombie-process case with its own recovery script — are documented as runbooks.

#Agent-Level Memory

Beyond the shared stores, each agent appends to its own MEMORY.md — a personal journal of domain knowledge (TraderBot's market-structure notes differ from Sentinel's threat notes). Scheduled jobs journal their outcomes there too, so an agent waking up for its daily task can see what its previous incarnations did.

#What This Buys

• Continuity: any session can answer "did we already solve this?" and usually has.
• Auditability: decisions carry timestamps and provenance; a memory that names a file or flag is treated as a point-in-time observation to verify, not a live fact.
• Compounding: the fleet's knowledge grows monotonically. The 60-bug historical catalog, the 17-item trading anti-pattern list, and the operational runbooks all emerged from accumulated observations rather than dedicated documentation sprints.