## Context

BooCode agents are stateless — they lose all context between sessions. The 3-tier memory architecture (Context→Daily→Core) provides structured persistence. Context compression reduces token waste. Boulder state enables work tracking across sessions. System Context provides typed context lifecycle management.

## Goals / Non-Goals

**Goals:**
- Cross-session agent memory via 3-tier architecture
- Token-efficient context window management via summarization + compression
- Work-in-progress persistence across sessions via boulder state
- Typed context sources with epoch baselines

**Non-Goals:**
- Distributed memory storage (single-user SQLite is sufficient)
- Real-time memory syncing across users

## Decisions

- **Embedding strategy**: Use OpenAI text-embedding-3-small via BooCode's existing provider. Store as BLOB in SQLite.
- **Vector search**: In-process cosine similarity (mathjs) — no external vector DB needed
- **FTS5**: SQLite FTS5 for keyword search with trigram tokenizer for CJK support
- **Memory tiers**: ContextTier (in-memory, per-session, LRU) → DailyTier (files, ~30-90 days) → CoreTier (SQLite, permanent)
- **Deep Dream**: Background cron job (configurable). Uses LLM (configured model) for consolidation
- **Boulder state**: Stored in Postgres `plans` table as JSONB. Auto-resume on session start.
- **Context compression**: DCP-style. Range dedup (remove duplicate messages), purge errors (remove redundant error messages), turn protection (keep turn boundaries intact).
- **SWR caching**: In-memory Map with TTU-based revalidation. Cache key = (tool, params hash). Invalidate on project switch.