Persistent Memory: Claude That Remembers

Keep it under 200 lines

Claude reads CLAUDE.md in full on every session. Long files waste context tokens and bury important instructions. Prune aggressively. If a rule is not enforced in 90% of sessions, remove it.

Use sections with clear headers

Organise by: Stack, Commands, Conventions, Architecture, DO NOT. Clear headers help Claude retrieve the right section quickly when it performs in-context search.

Put blocking rules in the DO NOT section

List hard constraints explicitly. "DO NOT use npm or yarn" is clearer than burying it in the stack section. Negatives get top-of-mind attention.

Reference, don't repeat

Use @filename.md to pull in project-specific files. Keep CLAUDE.md as the index, not the encyclopedia. Put the details in the referenced files.

Review and prune every 30 sessions

Rules decay. A constraint that was critical in month 1 may be solved by tooling in month 3. Dead rules add noise and reduce the signal-to-noise ratio for the model.

Accumulates learned patterns from sessions

Format: Short bullet: problem → solution → why it works

Example: n8n webhook nodes require explicit 30s timeout in prod; default 10s drops on Vercel edge.

Documents every solved blocker so it never recurs

Format: Date · Symptom · Root cause · Fix · Prevention

Example: 2026-04 · Prisma type errors on deploy · prisma generate not in build script · add to pnpm build.

Timestamped session log written by auto-memory hook

Format: Goal → Actions → Decisions → Learnings

Example: Auto-written on session end by the PostToolUse hook.

Stop hook: session logger

Fires when a Claude session ends. Writes a timestamped summary to memory/sessions/. Captures what was built, decisions made, and patterns observed.

// .claude/settings.json
{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [{
          "type": "command",
          "command": "node scripts/memory-logger.js"
        }]
      }
    ]
  }
}

PostToolUse hook: pattern extractor

Fires after every tool call. When Claude writes a file or runs a command, this hook checks for patterns worth persisting: new conventions, resolved errors, repeated solutions.

// .claude/settings.json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Bash",
        "hooks": [{
          "type": "command",
          "command": "node scripts/pattern-extractor.js"
        }]
      }
    ]
  }
}

memory-logger.js: minimal implementation

// scripts/memory-logger.js
const fs = require("fs")
const path = require("path")

const date = new Date().toISOString().split("T")[0]
const dir = path.join(process.cwd(), "memory", "sessions")
fs.mkdirSync(dir, { recursive: true })

const entry = [
  `# Session - ${date}`,
  `## Timestamp`,
  new Date().toISOString(),
  `## Learnings`,
  process.env.CLAUDE_LEARNINGS ?? "(none captured)",
  "",
].join("\n")

fs.appendFileSync(path.join(dir, `${date}.md`), entry)