baseline by friedbotstudio/ docs
friedbotstudio/baseline

Reference

Memory.

The memory system at .claude/memory/ accumulates project facts across sessions. Seven canonical files hold long-term knowledge; two underscore files handle staging and continuity.

A re-verified anchor at the center, seven canonical entries on the inner ring, and an unverified candidate stream on the outer dotted ring. re-verify on cite

§ I

The shape

Memory lives at .claude/memory/. Seven canonical files hold long-term project knowledge. Two underscore files serve transient roles: a staging inbox and a session-continuity snapshot. The underscore files are gitignored.

FilePurpose
landmarks.mdFiles, modules, and symbols worth remembering across sessions, with stable line references.
libraries.mdPinned versions and gotchas for third-party libraries used in the project.
decisions.mdArchitectural choices and the reasoning behind them, recorded close to the moment they were made.
landmines.mdPatterns that look right but fail in this codebase. Each entry names the trap and the safe alternative.
conventions.mdProject-specific style or structure rules that diverge from common defaults.
pending-questions.mdOpen questions for the user. Skill outputs append here when something needs human resolution.
backlog.mdFuture-work intent captured automatically from user prompts and assistant text. Stale-exempt; closed via superseded-at: when an item is picked up or dropped.
_pending.mdAuto-extraction inbox. The memory_stop hook appends candidates each turn-end. Curate via /memory-flush.
_resume.mdSession-continuity snapshot. Refreshed every turn-end and before context compaction.

§ II

What memory is, and isn't

Memory is for facts that survive the session and that cannot be recovered cheaply by reading the codebase. Library pin reasons, the locations of long-lived hot paths, decisions whose rationale is not obvious from the diff.

Memory is not a place to record code patterns or conventions that the code itself already shows. The session-start hook injects a one-page index of memory plus a short resume snapshot into your additional context. Files are read on demand by the relevant skill. The scout skill reads landmarks; research reads libraries; integrate reads landmines. Every cited entry is re-verified before use.

§ III

The lifecycle

Memory accumulates in a deliberately small loop. Each step is owned by a single hook or skill, and each touches exactly one canonical surface.

edit → landmark context7 → library text → backlog re-verify ok correct · delete turn end memory_stop staging _pending.md curate /memory-flush canonical 6 decay + 1 exempt cite re-verify on use 01 · auto-extract 02 · review 03 · promote 04 · cite
The loop. Three signals (file edits, context7 queries, anchored intent text in user prompts or assistant responses) stream into _pending.md at every turn end. /memory-flush promotes keepers to the seven canonical files: six participate in re-verification on every cite (failed verifications correct or delete in the same run), and one (backlog.md) carries intent that does not decay.
picked-up dropped superseded-at superseded-at open new entry picked-up into a workflow dropped decided against auto-close next /memory-flush
Backlog entries. A new item lands as status: open. Two terminal transitions exist. An entry becomes picked-up automatically when a workflow's /commit step runs against a workflow.json that names the entry in source_backlog_keys; the commit step invokes sweep.py stamp-closure on the named entries. An entry becomes dropped through a manual edit when the team decides not to pursue it. Both transitions write superseded-at: <ISO date>; the next /memory-flush Step 0a sweep deletes the block. The body status: field disambiguates which transition fired at the moment of close; the full record persists in git history.
  1. The memory_stop hook runs at the end of each Claude turn and emits three kinds of candidates into _pending.md: file-edit events become landmark candidates, context7 queries become library candidates, and anchored line-start intent text (in user prompts or assistant responses) becomes backlog candidates.
  2. At session start, the index lists the _pending.md row alongside the canonical files. backlog.md is stale-exempt; it never shows up in the stale count regardless of verified-at age.
  3. /memory-flush runs at workflow Phase 10.6 (between /archive and /grant-commit); the session-start nag fires only on candidates carried over from a prior incomplete workflow. /changelog is the sibling phase that runs immediately after /grant-commit at sub-step 11.5, before /commit at Phase 11.
  4. /memory-flush reviews each candidate, promotes keepers to the appropriate canonical file (landmark, library, backlog, decision, and so on), drops the rest, and clears _pending.md.
  5. Skills that consume memory (scout, research, integrate, simplify) re-verify each entry on cite. For the six decay-managed files, failed verification corrects or deletes the entry in the same run.
  6. Backlog entries do not participate in decay. They close instead through an explicit status transition: picked-up when an item enters a workflow as an intake, or dropped when the team decides against pursuing it. Both write superseded-at:; the next /memory-flush Step 0a sweep deletes the block.

§ IV

Re-verification before citation

Every skill that cites a memory entry re-verifies it. Verification means: the file still exists, the symbol is still at the named line, the library version is still pinned.

A landmark that says src/auth/session.ts:42 — token rotation is checked: file present, line still relevant. If the line moved, the skill updates the entry. If the symbol is gone, the skill deletes the entry.

This is the discipline that keeps memory load-bearing rather than misleading. A stale entry that says X exists can be worse than no entry at all because it leads to confident wrong recommendations. Re-verification catches drift early.

§ V

Pruning and staleness

The size cap is 500 entries per canonical file. When a write exceeds the cap, the same write prunes the oldest unverified entries. Entries unverified for thirty commits or ninety days are stale; the next phase that touches them either re-verifies or deletes.

Memory accelerates triage. It never authorizes a skip.

An entry can suggest where to look or which library to consult, but it cannot waive a phase, an approval gate, or a verify verdict. Workflow ordering is enforced by hooks, not by memory.

§ VI

Entry schema

Canonical files share a small, line-oriented schema. Each entry has a stable key, a one-line claim, a verification target (file path or symbol), and a last-verified marker. The schema lives in .claude/memory/README.md.

# landmarks.md
id: lm-2026-04-12-001
claim: token rotation runs on every refresh
target: src/auth/session.ts:42 (rotateOnRefresh)
added: 2026-04-12
verified: 2026-04-29  # self-healing rule: re-verify on every cite