> ## Documentation Index
> Fetch the complete documentation index at: https://docs.openlegion.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Memory System

> Five layers of persistent, self-improving memory

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
```

## Embedding & Vector Search

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

| Tool            | Purpose                                                                       |
| --------------- | ----------------------------------------------------------------------------- |
| `memory_search` | Hybrid search across workspace files (BM25) and structured DB (vector + FTS5) |
| `memory_save`   | Save 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.

| File                       | Cap            | Purpose                                                                         |
| -------------------------- | -------------- | ------------------------------------------------------------------------------- |
| `SOUL.md`                  | 4K             | Agent personality and behavioral instructions                                   |
| `INSTRUCTIONS.md`          | 12K            | Operator-edited fleet instructions — loaded into system prompt                  |
| `USER.md`                  | 4K             | User preferences and context                                                    |
| `MEMORY.md`                | 16K            | Curated long-term facts                                                         |
| `INTERFACE.md`             | 4K             | Cross-agent interface contract (capabilities, calling conventions)              |
| `AGENTS.md`                | 12K            | Engine-root agent descriptions (CLAUDE.md symlink)                              |
| `HEARTBEAT.md`             | uncapped       | Autonomous monitoring rules                                                     |
| `PROJECT.md`               | read-only      | Optional project context (bootstrap-only)                                       |
| `SYSTEM.md`                | 6K (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.