tesseract-ripple/memory-protocol

Persistent Memory Protocol

Auto-setup for ~/claude-projects/ subdirectories

When working inside a subdirectory of ~/claude-projects/ for the first time (i.e., no MEMORY.md exists in the project root), bootstrap:

1. Create MEMORY.md in the project root:

# Project Memory — <Project Name>
> Maintained by Claude across sessions. Last updated: <date>

## Research Threads

## Key Decisions & Design Choices

## Notation & Conventions

## Proof Sketches & Partial Results

## References & Papers

## Open Questions & Future Directions

## Session Log
- <date>: Project memory initialized.

2. Create a project CLAUDE.md at ~/.claude/projects/<shadow-dir-key>/CLAUDE.md containing instructions to read/update the project MEMORY.md. The shadow-dir key is the absolute project path with / replaced by -.

3. Inform the user that project memory has been set up.

Adapt sections if the project is code-focused (e.g., replace "Proof Sketches" with "Architecture Decisions").

Tier structure

• Global (~/.claude/memory/MEMORY.md): user preferences, usage patterns, cross-project notes, session log. Does not store project-specific research content.
• Project (MEMORY.md in project root): research threads, key decisions, notation, proof sketches, references, open questions, session log.

Reading protocol

• Always read global memory at session start.
• If in a ~/claude-projects/ subdirectory, also read that project's MEMORY.md.
• Do this before substantive work.
• If the user references prior work or says "where were we", consult both files.

Writing protocol

• Update at most twice per session per file: once at a major milestone, once at session end.
• Use targeted edits (Edit tool) to the relevant section — never rewrite entire files.
• Keep entries compressed: 1-3 sentences per item.
• Route correctly: preferences/patterns → global; research content → project.

What NOT to record

• Routine formatting, typo fixes, or mechanical changes
• Full proof text (memory just points to .tex files)
• Verbose explanations — memory is a compressed index, not a narrative

Maintenance

• Keep Session Logs trimmed: ~15 entries in global, ~20 in project. Delete older ones.
• If a research thread is marked done, compress to a one-liner after one session.
• If any memory file exceeds ~300 lines, aggressively compress stale sections.

Cost budget

• Reading: ~free (small files, 1-2 reads per session).
• Writing: target ≤2 edit operations per memory file per session. Each edit ≤20 lines.
• Never spawn a subagent solely to update memory. Do it inline.
• If the session was trivial (quick question, small fix), skip updates entirely.