project-memory

Project Memory

The Problem This Solves

When Claude works on a multi-session project, every context compaction or session restart loses hard-won knowledge. The compaction summary captures what happened but loses the why — the failed approaches, the API quirks, the "don't do X because Y happens" lessons. This forces expensive re-learning cycles.

Project Memory prevents this by maintaining three persistent files that survive compactions and session boundaries. The key insight: write knowledge to disk before it's lost, and read it back before starting work.

The Three Files

1. orient.md (Quick Start — at project root)

The 30-second briefing. Read this first in any new session. Contains: one-paragraph project description, file map, key IDs/URLs, current status (one line per workstream), top 3-5 priorities. Target length: under 60 lines.

2. system-memory/MEMORY.md (Living State — replace, don't append)

Full current state. Rewritten each save. Contains: status of every workstream, active decisions and rationale, technical constraints and gotchas (the expensive knowledge), key references, open issues with priority, next priorities.

The technical constraints section is the most valuable part — things that cost hours to discover and seconds to forget.

3. system-memory/SESSION_LOG.md (History — append only)

Chronological record. Each session/checkpoint gets an entry appended. Contains: session number and date, what was accomplished, key decisions, files modified, issues discovered.

When to Initialize

Create these files when ANY of these are true:

• User starts a project spanning multiple sessions
• User mentions remembering, not forgetting, or picking up later
• Existing orient.md or system-memory/MEMORY.md detected (activate and maintain)
• Project involves 3+ files, external APIs, or deployment steps
• Task will clearly take more than one session
• Conversation has had a compaction (the "continued from previous" message)

Do NOT wait for the user to ask. Initialize proactively for non-trivial projects.

Initialization

Starting fresh:

1. Create orient.md at project root and system-memory/MEMORY.md + system-memory/SESSION_LOG.md
2. Populate with what you know so far (even if sparse)
3. Tell the user: "I've set up project memory. This keeps progress safe across sessions."

Resuming (files exist):

1. Read orient.md first (quick orientation)
2. Read system-memory/MEMORY.md (full current state)
3. Read system-memory/SESSION_LOG.md (history)
4. Append new session entry to SESSION_LOG.md
5. Proceed — you should have full context without re-learning

Save Protocol

When to save:

• After completing significant work
• After discovering a technical constraint or gotcha — write it immediately, not later
• After decisions that affect future work
• Before generating lots of output (accelerates compaction)
• When conversation is getting long
• Every ~30 minutes of active work
• When user says "save", "remember this", "don't forget"

What to save:

• orient.md: Update status and priorities only
• system-memory/MEMORY.md: Full rewrite with current state, especially new technical constraints
• system-memory/SESSION_LOG.md: Append checkpoint entry

Compaction recovery:

When a session starts with a compaction summary, the memory files are more reliable than the summary for technical details. Always prefer the files, then update them with any new info from the summary.

Writing Good Memory Content

Technical constraints (highest-value content):

Bad: "Webflow scripts have limits" Good: "Webflow inline registered scripts are limited to 2000 characters. Scripts exceeding this must use a bootstrap/loader pattern that fetches from an external CDN."

The pattern: specific constraint + what happens if violated + what to do instead.

Status updates:

Bad: "Homepage is mostly done" Good: "Homepage (/) — LIVE on forma-prime.webflow.io. Footer uses .media-footer-item. RSS removed. Nav working. Open: footer alignment."

Priorities:

Bad: "Fix some bugs" Good: "1. Remove News password protection (manual: Webflow Designer > Page Settings). 2. Configure DNS. 3. Add openDrawer() to Portfolio."

Effort Tracking

Include in MEMORY.md: session count, approximate user time invested, number of compactions, total tool calls (rough compute measure). This makes the cost of re-learning visible.