Skip to main content
Five layers give agents persistent, self-improving memory across sessions.

​
Memory Layers

Layer 5: Context Manager          <- Manages the LLM's context window
  |  Monitors token usage (tiktoken for OpenAI, 3.5 chars/token Anthropic,
  |    4 chars/token fallback)
  |  Proactive flush facts at 60% capacity
  |  Auto-compact summarize at 70% capacity
  |  Warning at 80% capacity
  |  Extracts facts before discarding messages
  |
Layer 4: Learnings                <- Self-improvement through failure tracking
  |  learnings/errors.md         (tool failures with context)
  |  learnings/corrections.md   (user corrections and preferences)
  |  Auto-injected into system prompt each session
  |
Layer 3: Workspace Files          <- Durable, human-readable storage
  |  SOUL.md (4K cap)             (personality + behavioral instructions)
  |  INSTRUCTIONS.md (12K cap)    (loaded into system prompt)
  |  USER.md (4K cap)             (user preferences and context)
  |  MEMORY.md (16K cap)          (curated long-term facts)
  |  INTERFACE.md (4K cap)        (cross-agent interface contract)
  |  AGENTS.md (12K cap)          (engine-root agent descriptions)
  |  HEARTBEAT.md (uncapped)      (autonomous monitoring rules)
  |  PROJECT.md (read-only)       (optional project context, bootstrap-only)
  |  SYSTEM.md (6K cap, read-only, auto-generated, 5-min refresh)
  |  memory/YYYY-MM-DD.md         (daily session logs)
  |  Total bootstrap injection cap: 48K chars
  |  BM25 search (k1=1.5, b=0.75) across markdown files
  |
Layer 2: Structured Memory DB     <- Hybrid vector + keyword
  |  SQLite + sqlite-vec + FTS5
  |  Facts with embeddings — text-embedding-3-small (1536 dims)
  |  Auto-categorization with category-scoped search
  |  3-tier retrieval: categories -> scoped facts -> flat fallback
  |  Hybrid scoring: (0.7 * vector + 0.3 * keyword) * decay_score
  |
Layer 1: Salience Tracking        <- Prioritizes important facts
     SALIENCE_DECAY_RATE=0.95
     Access-count boost capped at 10.0
     High-salience facts auto-surface in initial context
The structured memory store uses OpenAI text-embedding-3-small (1536 dimensions) for vector search. Two important behaviors:
  • Non-OpenAI providers degrade to keyword-only. If no OpenAI key is configured the embedding provider defaults to "none" and the store falls back to FTS5 keyword search.
  • Auto-disable on consecutive failures. After 3 consecutive embedding failures the store silently disables vectors for the process lifetime (keyword search continues). Restart to retry.

​
Write-Then-Compact Pattern

Before the context manager discards messages, it:
  1. Asks the LLM to extract important facts from the conversation
  2. Stores facts in both MEMORY.md and the structured memory DB
  3. Summarizes the conversation
  4. Replaces message history with: summary + last 4 messages
Nothing is permanently lost during compaction.

​
Cross-Session Memory

Facts saved with memory_save are stored in both the workspace (daily log) and the structured SQLite database. After a reset or restart, memory_search retrieves them via hybrid search: 
Session 1: User says "My cat's name is Whiskerino"
           Agent saves to daily log + structured DB

  === Chat Reset ===

Session 2: User asks "What is my cat's name?"
           Agent recalls "Whiskerino" via memory_search

​
Memory Tools

ToolPurpose
memory_searchHybrid search across workspace files (BM25) and structured DB (vector + FTS5)
memory_saveSave fact to daily log + structured memory DB

​
Workspace Files

Each agent has a persistent workspace at /data/workspace/. The scaffold set (_SCAFFOLD_FILES) is six files: SOUL, INSTRUCTIONS, USER, MEMORY, INTERFACE, HEARTBEAT. AGENTS.md is symlinked from the engine root.
FileCapPurpose
SOUL.md4KAgent personality and behavioral instructions
INSTRUCTIONS.md12KOperator-edited fleet instructions — loaded into system prompt
USER.md4KUser preferences and context
MEMORY.md16KCurated long-term facts
INTERFACE.md4KCross-agent interface contract (capabilities, calling conventions)
AGENTS.md12KEngine-root agent descriptions (CLAUDE.md symlink)
HEARTBEAT.mduncappedAutonomous monitoring rules
PROJECT.mdread-onlyOptional project context (bootstrap-only)
SYSTEM.md6K (read-only)Auto-generated architecture guide + runtime snapshot, refreshed every 5 minutes
memory/YYYY-MM-DD.md—Daily session logs
learnings/errors.md—Tool-failure history
learnings/corrections.md—User-correction history
Direct writes to SOUL / INSTRUCTIONS / USER / MEMORY / INTERFACE / HEARTBEAT / AGENTS are blocked — agents must go through the update_workspace tool, which enforces caps and emits HTTP 413 when exceeded. Workspace bootstrap injection is capped at 48K total chars across all files.