Context Management

Route first — read this before anything else

Do not default to state.md for a map request. Do not default to project-map.md for a save-state request.

Purpose

Claude Code automatically compresses context within a session. This skill has two complementary responsibilities:

1. Cross-session persistence — state.md preserves decisions and progress for the current task when a session ends mid-work.
2. Accumulated project memory — session-log.md builds a searchable history of decisions, rejected approaches, and hard-won facts across sessions. Written manually via this skill — only when there is something worth preserving.

When to Use

• User explicitly asks to save state or compress context
• Work will continue in a new session and progress must be preserved
• Complex multi-step task has significant accumulated decisions/evidence
• Starting a new task on a project with existing history — grep the log first
• Repeated failures suggest the session has accumulated stale/conflicting context

Procedure

At the start of any non-trivial task

Before diving in, grep session-log.md for history relevant to the current task.

Step 1 — Extract keywords. Take the 2-3 most distinctive nouns from the task description. Avoid generic words ("fix", "update", "file") — use domain nouns ("hook", "auth", "deploy", "staleness").

Step 2 — Grep each keyword individually first:

grep -i "<keyword1>" session-log.md | tail -20
grep -i "<keyword2>" session-log.md | tail -20

Check the hit count before reading results. This tells you whether to narrow or widen before committing to any output.

Step 3 — Adjust based on hit count:

• 0 hits on all keywords → fall back to project-map.md Critical Constraints. Relevant history may have been promoted there instead of staying in the log. If still nothing, proceed without history.
• 1–10 hits → read them. Surface past decisions, rejected approaches, and constraints.
• >10 hits on one keyword → narrow with a second term: grep -i "<kw1>" session-log.md | grep -i "<kw2>" | tail -20

Step 4 — Surface what matters. If relevant entries are found, state them explicitly before proceeding: what was decided, what was rejected, what constraints apply. Don't silently absorb them — make them visible so the user can confirm or override.

When saving state (explicit invocation)

1. Extract durable artifacts only:

   • Approved design decisions
   • Active plan tasks and their status
   • Verified facts/evidence
   • Open questions/risks

   state.md vs plan.md:

   • plan.md (or docs/.../plans/*.md): the authoritative task list with checkboxes. Owned by executing-plans. Updated as tasks complete.
   • state.md: a session-boundary snapshot of where you are in the plan — current task, blockers, what's verified. It references the plan but does not duplicate the task list.

   If a plan exists, state.md should say "Executing plan at docs/.../plan.md, currently on Task 3" — not copy the full task list.

2. Write state.md at the project root with concise sections:
   • Current Goal
   • Decisions
   • Plan Status
   • Evidence
   • Open Issues
3. Check for superseded entries before appending. Grep session-log.md for 2-3 keywords from the current decision:

   grep -i "<keyword>" session-log.md

   Read any matching [saved] entries and ask: does the new decision directly contradict an old one? If yes, append [superseded by YYYY-MM-DD] to the old entry's header line — do not delete it. If the old entry is merely related but not contradicted, leave it unchanged. This is a judgment call, not a mechanical keyword match.
4. Append a [saved] entry to session-log.md:

What belongs here vs state.md:

• session-log.md [saved]: permanent decisions, anti-patterns to avoid, carry-forward open items
• state.md: active task status, in-progress plans, checklists, version bump readiness — anything that will be resolved soon

Never include in a [saved] entry:

• Test results or verification confirmations ("11/11 tests pass")
• Task checklists, file changelogs, or release notes → use state.md
• "How it works" walkthroughs → read the code
• Speculative analysis not approved for implementation → use a design doc in docs/
• One-time confirmations ("file deleted", "folder removed")
• Newly discovered permanent architectural constraints → add to project-map.md Critical Constraints instead

Hard limits per component — enforce while writing, not after:

• Goal: 1 line, ≤15 words
• Decisions: ≤5 bullets for multi-subsystem sessions, ≤3 for single-topic. Each bullet: decision + one-sentence why, ≤25 words total. No prose, no rationale beyond the why.
• Rejected: ≤3 bullets, ≤15 words each. What to avoid — not the full story of why it failed.
• Open: ≤2 items, ≤12 words each.

If a decision doesn't fit in 25 words, the explanation belongs in a design doc. Cut the explanation, not the decision.

Total entry backstop: 250 words / 1500 chars. If exceeded, a bullet violated its limit — find it and cut it. Typical single-topic sessions should target ~120 words; the higher cap exists for multi-subsystem sessions that genuinely touched 5+ areas.

## YYYY-MM-DD HH:MM [saved]
Goal: <one line>
Decisions:
- <what was chosen and the one-sentence why — not how it works>
Rejected: <what NOT to try, one line each — the anti-pattern knowledge>
Open: <carry-forward items only>

5. After appending the [saved] entry, update the stop-hook marker so the decision-log reminder resets:

   node -e "require('fs').writeFileSync(require('path').join(process.env.HOME||process.env.USERPROFILE||'.', '.claude','hooks-logs','last-saved-entry.txt'), new Date().toISOString())"

   This prevents the stop hook from re-firing the decision-log reminder on every subsequent stop in the same session.
6. In a new session, read state.md first to restore task context, then grep session-log.md for relevant history.

session-log.md Format and Maintenance

The log contains a single entry type:

• [saved] — written by this skill when explicitly invoked: full decision record including goals, rationale, rejected approaches, and key facts.

Nothing else writes to this file. The Stop hook reads it and reminds you to save, but it never appends. If a session's decisions are not saved through this skill, they are lost when the session ends.

File management:

• Lives at the project root alongside CLAUDE.md and package.json
• Keep under 200 entries — prune entries older than 6 months when it exceeds this
• When a decision is permanently superseded (e.g., the approach was replaced), mark it rather than deleting: append [superseded by YYYY-MM-DD]
• Do NOT log trivial sessions — a session with no decision worth carrying forward should leave no entry

For cross-project recall (finding how a similar problem was solved in a different codebase): session-log.md is per-project and keyword-searchable only. Cross-project recall is outside the scope of this system.

Project Map

project-map.md is the semantic memory layer — it captures the project's structure, key file purposes, and critical non-obvious constraints so that future sessions can orient without re-globbing or re-reading known files. Generate it once; update it when the project changes.

When to generate or update

• User says "map this project", "generate project map", or "update project map"
• First time setting up memory on a new project
• After a major refactor where many files moved or changed purpose

Generation procedure

1. Check for git:

   git rev-parse --git-dir 2>/dev/null

   • If git exists → record git rev-parse HEAD as the staleness hash.
   • If git does NOT exist → offer: "No git repository detected. Shall I run git init? It enables precise staleness tracking for project-map.md — creates a .git folder, touches none of your files. If you'd prefer not to, I'll fall back to file timestamp comparison instead, which works fine but is slightly less precise."
     • User confirms → run git init --quiet, then proceed with git hash.
     • User declines → use generation timestamp as the staleness marker.
2. Map the structure: Glob the project, identify the top-level directories and their purpose. Do not enumerate every file — summarise by directory.
3. Document key files: For each file that is load-bearing, non-obvious, or frequently referenced, write one line describing what it does and why it matters. Aim for 10–20 entries. Skip files whose purpose is obvious from their name.

4. Capture critical constraints: The highest-value section. These are non-obvious facts that are not visible in the code itself — quoting rules, platform differences, version sync requirements, things that caused bugs before. Pull these from session-log.md [saved] entries and from known-issues.md if they exist.

   Never repeat what CLAUDE.md or AGENTS.md already says. Those files are loaded into every session; the map is injected alongside them, so a duplicated constraint costs tokens twice and adds nothing. Read them first and leave out anything they cover — in this section and in Key Files.

5. Identify hot files: The files that change most often — the ones most likely to need a freshness check on future sessions.

   git log --name-only --pretty=format: --since=6.months | grep -v '^$' | sort | uniq -c | sort -rn | head -15

   Without git, fall back to the files most often named in session-log.md decisions. Do not look for Files: lines — that field belonged to [auto] entries, which were retired on 2026-04-04.
6. Write project-map.md at the project root — same level as CLAUDE.md and package.json, never in docs/ or any subdirectory. The session-start hook looks for it with ls project-map.md 2>/dev/null from the project root — if it's anywhere else, the hook cannot find it and every future session loses the map. Use this format:

# Project Map
_Generated: YYYY-MM-DD HH:MM | Git: <short-hash> | (or: Staleness: timestamps)_

## Directory Structure
<dir>/ — <one-line purpose>
<dir>/ — <one-line purpose>

## Key Files
<path> — <what it does and why it matters>
<path> — <what it does and why it matters>

## Critical Constraints
- <non-obvious fact that would cost time to rediscover>
- <non-obvious fact that would cost time to rediscover>

## Hot Files
<path>, <path>, <path>

Update procedure

When the staleness check in the entry sequence flags changed files:

1. Re-read only the flagged files.
2. Update their entries in the Key Files section.
3. Update the git hash / timestamp in the header.
4. If any new critical constraints were discovered this session, add them.

Size: 150 lines is the authoring target, 200 is the hard limit. Under 150, the map is doing its job. Between 150 and 200 it is still injected in full, but it has stopped being a map and become documentation — prune file entries whose purpose is now obvious. At 200+ the session-start hook stops injecting the full file and falls back to Critical Constraints and Hot Files only, so anything you wrote in Key Files silently stops reaching future sessions. Never let it cross 200.

Lines are not the only limit. All project memory shares one ~9,500-character injection budget, filled in order: state.md → Critical Constraints → open known issues → the latest session-log entries → the rest of the map. A 4,000-character Critical Constraints section pushes the latest decisions out of every session. Keep each constraint to one line and the section under ~1,500 characters; node tools/memory-health.js shows what was cut.

Guardrails

• Do not drop user-provided constraints.
• Do not rewrite requirements; preserve intent.
• If uncertain whether old context matters, keep a short reference in Open Issues.
• Keep state.md under 100 lines — if it's longer, it's not compressed enough.