project-memory

Purpose

Three files. Each has one job. Together they let any agent — or future-you — resume work cold without losing context or repeating dead ends.

Rules Before Writing Anything

1. Read all three files first. Never update blind.
2. Update only what changed. One new decision? One new entry. Not a rewrite.
3. CONTEXT.md is the only file that fully overwrites. The other two append only.
4. Failures are first-class. A root cause captured is a dead end avoided.
5. If nothing changed, say "No updates needed" and stop.

DECISIONS.md — Format

Each entry is an ADR (Architecture Decision Record). Once written, never edited. If a decision is reversed, add a new ADR that supersedes it.

# Decisions

## ADR-001: [Title]
**Status:** active | superseded by ADR-00X
**Decision:** One sentence — what was chosen.
**Why:** One to three sentences — the actual reason. Not obvious things.
**Do not:** What must never happen as a result of this decision.
**Failure mode:** What goes wrong if this is ignored.

What earns an ADR:

• Architectural choices (always-on vs on-demand, profile system, gatekeeper)
• Stack choices (uv not pip, Camoufox not Playwright raw)
• Security choices (localhost-only ports, no cookie rotation)
• Anything that, if reversed, would break something silently

What does NOT earn an ADR:

• Implementation details
• File naming
• Anything reversible without consequence

CONTEXT.md — Format

Fully overwrites every invocation. Stays under 20 lines.

# Context
**Updated:** YYYY-MM-DD

## Current Layer
Layer X — [name]. Status: [building | blocked | verified]

## Last Completed
[One line — what just finished and confirmed working]

## Active Blocker
[One line — what is broken or unclear right now. "None" if clear.]

## Next Action
[Exact next task. Specific enough that an agent can execute it cold.]

## Deferred
- [Thing explicitly set aside + why]

STACK.md — Format

Two sections. Append-only except version bumps.

# Stack

## Locked Versions
| Package | Version | Replaces |
|---------|---------|----------|
| camoufox | >=0.4.0 | raw Playwright for stealth |
| uv | latest | pip, venv, pyenv |
| ...

## Do-Not Patterns + Root Causes

### [Pattern name]
**Never:** [Exact thing to never do]
**Why:** [Root cause — what actually broke or will break]
**Instead:** [Correct pattern]

What earns a Do-Not entry:

• Anything that caused a real failure during this project
• Any 2025 pattern that was caught and rejected
• Any anti-pattern from the 2026 skills that applies here

Update Algorithm

1. Read DECISIONS.md, CONTEXT.md, STACK.md
2. Read last 5-7 conversation turns
3. Extract:
   a. New decisions made → append to DECISIONS.md
   b. New failures/root causes → append to STACK.md do-nots
   c. Version changes → update STACK.md locked versions
   d. Current state → overwrite CONTEXT.md
4. Write only changed files
5. Report: "Updated X, Y. Z unchanged."

Token Budget Rule

Each file has a hard cap:

• DECISIONS.md — 60 lines max. If full, archive old ADRs to references/decisions-archive.md
• CONTEXT.md — 20 lines max. Always.
• STACK.md — 80 lines max. If full, archive resolved do-nots.

Quality check before writing: Would removing this sentence lose information? If no → remove it.