Documentation snapshot: This describes an internal system as documented, not its current live status. Configuration, counts, and operating state may have changed.
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
-
Primary memory — a SQLite + vector-search store behind a background worker. Its design supports capturing observations about bugs, decisions, and discoveries for later semantic search.
-
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.
-
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. Because these files do not require the worker, they provide a separate path when it is unavailable.
Token-Efficient Recall
Recall follows a strict three-layer funnel to avoid drowning sessions in context:
- Search → compact index with IDs (~50–100 tokens per result)
- Timeline → chronological context around interesting hits
- Full fetch → complete details only for the filtered few (~500–1000 tokens each)
The staged approach limits how much context needs to be loaded before a relevant record is found. Its savings depend on the query and the source material.
The Resilience Protocol
The documented policy requires memory to be checked and failures to be reported. It was shaped by an 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: sessions can search for previous solutions and decisions.
- 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.
- Accumulated context: historical bug notes, trading anti-patterns, and operational runbooks make prior observations available for review.