Claude Memory Loop

claude-memory-loop

**A memory loop for Claude Code: one small file that every session reads first, on every surface — fed by a capture discipline whose every rule was paid for by a real failure.**

The problem

Every Claude session starts empty. Your chat sessions, CLI sessions, cloud sandboxes, and other agents don't share what they learned. Your notes vault is too big to re-read at session start — and an AI that "just reads everything" quietly trusts stale dates and re-does investigations a previous session already closed.

Bigger context windows don't fix this. What fixes it is the same thing that fixes it in hardware: **memory tiering**.

Tier	In hardware	Here	Property
Hot	HBM	Session context	Fast, rich, gone when the session ends
Warm	flash cache	BRIEF.md	Small, capped, always read first, shared by every surface
Cold	SSD	Your full repo/vault	Big, canonical, read on demand via pointers

The git repo is the only storage that crosses every surface boundary — local CLI, cloud sessions, chat (read-only via the GitHub MCP connector), and any other agent you run. So the warm layer lives in the repo.

The loop

  capture (6 types, 1 line each)          open decisions & deadlines
  memory/capture-log.md          ◀──────▶ open-loops.md
            │                                   │
            ▼                                   ▼
        BRIEF.md  ◀── tools/build_brief.py (caps + expiry + budget)
            │
            ▼
  every session reads it FIRST (SessionStart hook)
            │
            ▼
  human judges → promotions to your canon (human gate)
            │
            └── new judgments become new captures — the loop closes

Plus a **Stop hook**: on days a session produced real output, it asks for a short *session card* — what was done, **what was ruled out and why**, what assumptions it stands on. That's the part that normally evaporates, and it's what saves the next