Memory

CLI-JAW has a 3-tier memory system: structured file storage, episode-based conversation summaries, and semantic search with FTS5 indexing. Memory persists across sessions and is injected into the agent's system prompt.

Three Tiers

Memory Directory Structure

~/.cli-jaw/memory/structured/
├── profile.md          # User profile and preferences
├── shared/
│   ├── preferences.md  # Reflected preferences
│   ├── decisions.md    # Key decisions
│   ├── projects.md     # Project context
│   └── soul.md         # Soul and identity
├── episodes/
│   ├── live/           # Daily conversation summaries
│   └── imported/       # Imported from legacy memory
├── semantic/           # Categorized knowledge
├── procedures/         # Runbooks and procedures
├── sessions/           # (not indexed)
└── index.sqlite        # FTS5 search index

How Memory Works

1. History Block (Conversation Context)

On new sessions, the most recent conversation history (up to 8000 chars, 10 sessions) is prepended to the user prompt as [Recent Context]. This is scoped to the current workingDir.

2. Memory Flush (Conversation to Storage)

After every N assistant responses (default: 10, configurable via settings.memory.flushEvery), a separate agent extracts key information and appends it to the daily episode file.

## 15:30
User discussed refactoring the auth module. Decided to use JWT tokens.
Prefers ES Module only, no CommonJS.

3. Advanced Prompt Injection

When the FTS5 index is ready, the system prompt includes:

• Profile Context -- from profile.md (800 chars)
• Soul & Identity -- from shared/soul.md (1000 chars)
• Task Snapshot -- FTS5 search results relevant to the current prompt (up to 4 hits, 2800 chars)

CLI Commands

# Search memory
jaw memory search "JWT authentication"

# Read a memory file
jaw memory read shared/decisions.md

# Save to memory
jaw memory save shared/notes.md "New note content"

# List memory files
jaw memory list

# Initialize memory
jaw memory init

# Reflect recent episodes into structured memory
jaw memory reflect

# Trigger memory flush
jaw memory flush

# Cleanup old entries
jaw memory cleanup --days 30

Slash Commands

L1 / L2 Memory Boundary

Dashboard Embedding (Optional)

The dashboard supports optional vector embedding on top of FTS5 search. This is an add-on layer that is off by default. Supported providers: OpenAI, Gemini, Voyage, Vertex, Local (Ollama).

# Configure via dashboard settings or CLI:
jaw dashboard memory config set --provider openai --api-key sk-...
jaw dashboard memory reindex --embedding

Memory Settings

{
  "memory": {
    "enabled": true,
    "flushEvery": 10,
    "cli": "claude",
    "model": "haiku"
  }
}