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.

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 session from repeating the investigation.

Install

This repo is a Claude Code skill. Two steps:

1. Install it (pick one):

   # via the skills CLI (skills.sh ecosystem)
   npx skills add Elliotoh-jin/claude-memory-loop --agent claude-code
   
   # or plain git, into your user-level skills folder
   git clone https://github.com/Elliotoh-jin/claude-memory-loop.git ~/.claude/skills/memory-loop-setup
   

2. Open Claude Code in the target repo and say:

   "Set up the memory loop in this repo."

The skill confirms your domains (2–5, e.g. investing · career · projects), scaffolds the files below, merges the hooks without touching your existing ones, and runs the first build — it works on a completely empty repo.

The discipline (this is the actual product)

The plumbing is ~300 lines. The value is the rules — each one exists because its absence measurably broke the loop:

• Six capture types only — hypothesis · falsification · principle · bias · question · shift. A falsification (a broken assumption) is the most valuable line you can write. Instructions, greetings, and status chatter are never captured.
• Three closing doors — an open item closes by resolution, rejection (with the reason, so it's never re-investigated), or expiry. Leaving items open-but-dead is the worst outcome: the registry rots into an archive.
• The shelf has a budget — hard caps per section, a byte budget overall, 21-day windows, 30-day card expiry. A warm layer dies by growing. The moment you want to raise a cap is the moment to close sources instead.
• Human gate — the AI proposes; only a human judgment promotes anything into your profile or principles canon. And verify an agent's report of a canon write against the actual diff (see field note 4).
• Deadman switch — any open item can carry a due ~MM-DD marker; once the date passes with the item still open, BRIEF's header warns every surface until someone judges it or moves the date.

Field notes — why these rules exist

From six weeks of running this on a real personal repo (private) before packaging it:

1. The write-only loop. Two weeks in, the infrastructure kept growing while actual captures stayed at zero — the loop produced output nobody consumed. Diagnosis: capture friction, not absence of thinking (a "what did you actually look at these two weeks?" test got an instant answer that had never been written down). Hence: one-line captures, and optional nudges that ask instead of waiting.
2. Fossilized catalysts. A D-day list went 27 days stale and every date on it was wrong — sessions kept trusting it as fact. Hence the freshness header: the system now warns about its own staleness, and the first thing it ever caught was itself.
3. The deadman's first day. The deadline-watch shipped and immediately flagged three decisions that had silently sat 15–47 days past their own review dates. Nobody had noticed. Watching files go stale is not the same as watching decisions go stale.
4. Report ≠ commit. An automated agent reported "kept on hold" about a proposal item — while its actual commit had quietly promoted that item into the principles canon. Caught only by diffing the commit. Hence: agent reports about canon writes are verified against the diff, always.

Optional extensions (later, once material accumulates)

• Morning nudge / evening sweep — a resident agent (cron) that asks you 2–3 open questions each morning and captures your answers each evening. Any always-on agent works; the loop runs fine without it.
• Profile mining — after ~4 weeks of captures, mine them for your decision style, principle candidates, blind spots, and needs — as an evidence-cited proposal, never an automatic promotion.
• Chat as a read-only surface — connect claude.ai chat to the repo with the GitHub MCP connector's readonly endpoint + a read-only GitHub App. Chat reads the warm layer; writes stay with surfaces that pass through your hooks and gates. Read O / write X — by design, not by limitation.

FAQ

Does this work with Obsidian? Yes — everything is plain markdown in a git repo; point your vault at it. Does it need any dependencies? Python 3 standard library, bash, git. Nothing else. Will it fight my existing setup? The installer never overwrites existing files and merges hooks non-destructively; if it finds a previous installation it stops and reports instead. Where did this come from? Built and battle-tested (in Korean) on a private personal second-brain repo; this is the English packaging of the structure and its rules.

License

MIT