MEMORY_ARCHITECTURE.md
Table of Contents

- Memory & Context Architecture
- Four-Tier Architecture
- Data Flow
- File Locations
- Key Design Principles

# Memory & Context Architecture

> How Claude Code + Empirica loads, stores, and retrieves knowledge across sessions.

## Four-Tier Architecture

Diagram 1
Click to expand

## Data Flow

Diagram 2
Click to expand

## File Locations

Scope | Path | Purpose
--- | --- | ---
Global | `~/.claude/CLAUDE.md` | User instructions (includes Empirica system prompt)
Global | `~/.claude/settings.json` | Hooks, plugins, statusline configuration
Global | `~/.empirica/` | Global state (active_work, instance_projects, config)
Global | `~/.empirica/workspace.db` | Cross-project entity registry
Per-project | `{project}/.claude/CLAUDE.md` | Project-specific overrides
Per-project | `{project}/.empirica/sessions/sessions.db` | All epistemic data
Per-project | `{project}/.empirica/active_transaction_*.json` | Open transaction state
Per-project | `{project}/.empirica/hook_counters_*.json` | Tool call counts
Per-project | `{project}/.breadcrumbs.yaml` | Calibration data (auto-updated)
Per-conversation | `~/.claude/projects/{path}/memory/` | Auto-memories (CC native)
Per-conversation | `~/.claude/projects/{path}/*.jsonl` | Full transcripts

## Key Design Principles

1. Tier 1 is token-budgeted — MEMORY.md capped at 200 lines, system prompt is lean (~1200 tokens)
2. Tier 2 is hook-injected — Loaded only when relevant, via SessionStart and PREFLIGHT hooks
3. Tier 3 is queried — Never bulk-loaded. CLI commands and Qdrant search retrieve specific data
4. Tier 4 is ephemeral — Auto-cleaned by stale file detection and session-end hooks
5. No CWD fallback (mid-session) — Project resolution uses instance files, not filesystem. Exception: `startup` events prefer CWD over stale instance files
6. Git notes are portable — Epistemic state survives repo clone/transfer via `--ref=breadcrumbs`
7. Qdrant is optional — Core works without it. Semantic search and pattern injection require it.

100%
Scroll to zoom · Drag to pan · Esc to close