ENGRAM — Memory System

Inbox-first, file-native memory layer for Claude sessions. Plain Markdown in ~/.claude/. Claude reads it automatically. You capture without decisions.

Locked Configuration

These decisions are final. Do not re-litigate them.

Machine constants: MacBook Pro M5 Pro · Apple Silicon · /opt/homebrew · iTerm2 · zsh Workspace: ~/Projects (alias ~/Code) · Map: ~/Code/WORKSPACE.md · Repo: mazze93/projects-workspace

File Architecture

~/.claude/
├── CLAUDE.md              ← Claude reads this automatically (Claude Code + Cowork)
└── memory/
    ├── inbox.md           ← append-only capture log; never reorganized manually
    ├── identity.md        ← who Mazze is, machine config, preferences
    ├── projects.md        ← Claude-specific context per project (status, open questions, decisions)
    ├── patterns.md        ← recurring conventions across projects
    └── decisions.md       ← architectural decisions log

~/Code/{repo}/
└── CLAUDE.md              ← per-repo scoped context; created on demand via engram-stub-repo

~/Code/WORKSPACE.md        ← authoritative project registry (source of truth for project list/domains)

Mode Routing

Identify the mode from user intent, then execute that mode's steps in full.

Mode 1 — Setup

Run on first-time setup or reinstall on a new device.

1. Read references/setup-script.sh.
2. Write the script to ~/engram-setup.sh using the Write tool, or present it for the user to copy if write access is unavailable.
3. Tell the user to run:

   chmod +x ~/engram-setup.sh && ~/engram-setup.sh

4. After the script completes, ask: "Run brain-dump session now to populate memory files, or continue later?"
5. If now → go to Brain-dump mode.

Restore path (existing memory on the GitHub remote): m3.local does not resolve from this machine (checked 2026-09-12) and identity.md only ever listed it as a candidate remote, never a wired one — so do not plan a restore around it. Memory lives on GitHub. Restore from mazze93/dotfiles-claude before running the setup script, so nothing is overwritten:

git clone https://github.com/mazze93/dotfiles-claude.git ~/.claude   # fresh machine
git -C ~/.claude pull                                                # or, if ~/.claude exists

Then run the setup script to scaffold any missing files and install shell additions.

Mode 2 — Brain-dump

Populate all memory files from scratch via structured interview.

Read references/brain-dump-interview.md and run the full interview. Do not skip or batch sections. After each section, write the corresponding file before moving to the next. All writes use the Write tool (or Bash echo for appends).

Files produced in order:

1. ~/.claude/memory/identity.md
2. ~/.claude/memory/projects.md
3. ~/.claude/memory/patterns.md
4. ~/.claude/memory/decisions.md
5. ~/.claude/CLAUDE.md — synthesized last, from the four above

Post-restore variant: Use the interview to update files rather than replace. Identify stale content, add missing context, and prefix outdated entries with [STALE].

Mode 3 — Capture

Handle natural-language memory capture mid-session.

1. Extract the core fact, decision, or context item from the user's message.
2. Format it: YYYY-MM-DD HH:MM: [content]
3. Append to ~/.claude/memory/inbox.md via Bash:

   echo "$(date '+%Y-%m-%d %H:%M'): [content]" >> ~/.claude/memory/inbox.md

4. Confirm: → captured to inbox

Rules:

• Never categorize, tag, or route at capture time. Inbox is append-only.
• Never modify any file other than inbox.md in this mode.
• If running in Cowork without shell access to ~/.claude/, output the formatted entry as text for the user to paste manually.

Shell path (wired by setup script — no action needed):

remember "text here"

Mode 4 — Consolidate

Run when the user explicitly requests consolidation. Never run automatically.

Consolidation is performed inline by these steps. There is no separate skill.

1. Read ~/.claude/memory/inbox.md. Each capture is one line, YYYY-MM-DD HH:MM: text. If the only content is the header and the HTML comment, there is nothing to process — say so plainly (0 entries) and go to step 4. Never manufacture consolidation work out of an empty inbox.

2. Route each entry to exactly one structured file, preserving its date:

   Entry is about	Goes to
   who Mazze is, machine config, tooling preference	identity.md
   a specific project's status, open question, in-flight state	projects.md
   a convention that recurs across projects	patterns.md
   a dated choice with a rationale	decisions.md (format: YYYY-MM-DD · scope · decision · rationale)
   Append under the appropriate ## heading — never rewrite or reorder existing
   content. An entry that fits nowhere stays in the inbox; report it as unrouted
   rather than forcing it into a file.

   Entries starting [promote] come from session-journal's close-out. Route them by gist like any other entry, and carry the -> <pointer> across as a source suffix — for decisions: YYYY-MM-DD · scope · decision · rationale · src: <pointer>. ENGRAM holds the pointer, never a copy of the journal text.

   Pointer liveness (the rot rule, applied to memory) — before writing a [promote] entry, check its pointer:

   • <repo>/docs/journal/<file> § <title> — the file exists and grep -F '<title>' <file> finds the title.
   • stratum:<log>/<dec> — resolve with stratum status <dec> --log <log>. If Stratum is unreachable, mark it src: [UNVERIFIED-SRC] <pointer>.
   • Dead pointer — mark it src: [DEAD-SRC] <pointer> and list it in the report as outstanding. Never drop the entry.

   Markers go inside the src: suffix, never at the start of the line: the line must still begin with its date or engram-mark-stale (which matches ^YYYY-MM-DD) stops ageing it. [DEAD-SRC] is not [STALE]: stale means old per D-06; dead-src means the citation no longer resolves.

   Liveness only reports; it never blocks consolidation or push-memory.

3. Once every entry is written and the writes are verified, truncate inbox.md back to its two header lines. Processed entries live in the structured files from then on; the inbox is a buffer, not an archive.
4. Run stale decay marking:

   engram-mark-stale   # installed by setup script

   The function always prints "stale items marked" whether or not it changed anything, so verify the real count yourself: grep -c '\[STALE\]' ~/.claude/memory/*.md.
5. Commit and push. push-memory does git add -A across ~/.claude, which holds session transcripts and credentials; that directory's .gitignore is a deny-by-default allowlist that keeps them out. Read git status --short before pushing, and prefer staging explicit paths (memory/ CLAUDE.md) over the blanket sweep.

   push-memory         # installed by setup script

6. Report: entries processed, entries unrouted, stale items flagged (counted, not assumed), [DEAD-SRC] / [UNVERIFIED-SRC] pointers written, git push status.

Stale decay rule: Any dated entry (line beginning YYYY-MM-DD) older than 60 days receives a [STALE] prefix. Items are never deleted automatically. The user triages [STALE] items manually at the next consolidation.

Mode 5 — Surface

Present a compact context digest. Read directly from files — never infer or fabricate.

Format:

── ENGRAM ────────────────────────────────────────
Machine: M5 Pro · /opt/homebrew · iTerm2 · zsh

Active projects:
  · [list from projects.md ## ACTIVE section]

Last inbox entries:
  [last 3 non-blank, non-comment lines from inbox.md]

[If project-scoped]: {Project} context:
  Stack:          [from per-repo CLAUDE.md]
  Status:         [active / maintenance / paused]
  Open questions: [list]

[If stale items exist]: ⚠ stale items present — run consolidation
──────────────────────────────────────────────────

If a memory file is missing, say so explicitly: identity.md not found — run brain-dump to populate. Do not guess at content.

Guardrails

• Never overwrite existing memory file content outside of Mode 2. Inbox is append-only. Structured files are updated only through Mode 4's routing steps.
• Never fabricate project context not present in memory files. Missing context is surfaced as a gap, not filled in.
• No auto-consolidation. D-04 = manual. Consolidation requires explicit user request.
• precmd digest stays compact: ≤8 lines. Verbose terminal output defeats the purpose.
• All paths use $HOME — never hardcode /Users/mazze/.
• [STALE] is additive: prefixes are added, never removed automatically.
• Per context-synapse: operational context inference is a permanent hard stop. Never suggest, implement, or discuss it.
• Per secure-pride: any auth, identity, or data-handling change requires explicit GDPR/CCPA/SOGI compliance check before proceeding.

References

• references/setup-script.sh — complete idempotent bash setup script
• references/brain-dump-interview.md — structured interview, 5 sections, workspace-aware (reads WORKSPACE.md)
• references/repo-stubs.md — generic + domain-specific CLAUDE.md templates; use engram-stub-repo for any project