Persistent state across context compaction

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

Feature request: Persistent state across context compaction

The Problem

When Claude Code compacts context mid-session, it loses track of project state, in-progress work, decisions made, and what it was doing. For long sessions on complex projects, this means Claude asks "what are we working on?" after every compaction — sometimes multiple times per session.

This is the single biggest friction point for power users. Context compaction is necessary (windows are finite), but the information loss is not.

Proposed Solution

What I Built

I wrote MemoryForge — a zero-dependency memory layer that hooks into Claude Code's lifecycle to survive compaction cycles. 780 lines of Node.js, 3 hooks, 6 MCP tools.

The core mechanism is a compaction survival loop:

Session starts ───> Hook reads .mind/ ───> Briefing injected into context
     ^                                              |
     |                                              v
     |                                        Work happens
     |                                              |
Hook re-injects <─── Context compacted <─── Hook saves checkpoint
briefing (source=compact)

1. SessionStart hook reads state files from .mind/ and injects a briefing via additionalContext
2. Claude works, context grows
3. PreCompact hook fires, saves a checkpoint to .mind/checkpoints/latest.md
4. Context compacts
5. SessionStart fires again with source=compact — hook detects this and re-injects the full briefing plus the checkpoint

The result: Claude picks up exactly where it left off after compaction. No "what were we doing?" moment.

State is stored in four human-readable Markdown files (.mind/STATE.md, PROGRESS.md, DECISIONS.md, SESSION-LOG.md), queryable via MCP tools mid-session.

The API Stability Question

This entire system depends on undocumented behavior of Claude Code's hook system:

1. SessionStart fires after compaction with source=compact — This is the critical signal that tells my hook "context was just lost, re-inject everything." If this event stops firing, or the source field changes, the survival loop breaks silently.

1. additionalContext in hookSpecificOutput is injected into Claude's context — This is how the briefing gets into the model's working memory. If the return contract changes, briefings stop appearing with no error.

1. PreCompact fires before compaction with time to write files — My hook needs enough time to read state and write a checkpoint before compaction proceeds. If the timeout is too short or the event stops firing, checkpoints are lost.

1. SessionEnd fires on exit — Used for activity tracking and auto-generated session summaries. Less critical, but still part of the loop.

None of these are documented as stable API. I'm building on implementation details that could change in any CLI update.

The Request

Can these hook behaviors be stabilized or documented?

Specifically:

| Behavior | Current Status | Request |
|:---------|:---------------|:--------|
| SessionStart fires after compaction | Works, undocumented | Document as stable, or provide an alternative event |
| source field in SessionStart input | Works (startup, resume, compact) | Document the enum values |
| additionalContext return path | Works, undocumented | Document as the canonical way to inject context from hooks |
| PreCompact event exists | Works, undocumented | Document trigger timing and timeout guarantees |
| Hook input/output JSON schema | Informal, inferred from behavior | Publish a schema or TypeScript types |

I'm not asking for new features — just stability guarantees on behavior that already exists and works.

Why This Matters Beyond MemoryForge

The compaction survival loop is a general primitive. Any tool that wants to maintain state across compaction needs these same guarantees:

• Project management tools that track tasks across sessions
• Code review tools that remember review context
• Learning/tutoring tools that track student progress
• Any MCP server that needs to restore state after compaction

If the hook API is stable, an ecosystem of tools can build on it confidently. If it's not, every tool is one CLI update away from silent failure.

Alternative Solutions

Alternative: Native Support

If Anthropic is planning to solve compaction memory loss natively (which would be ideal), I'd love to know. MemoryForge exists because the gap exists — if the gap closes, the tool becomes unnecessary, and that's a good outcome.

Either way, we are running MemoryForge today within our 50+ engineers using Claude Code which is evidence that this problem is real and worth solving, whether externally or internally.

Priority

High - Significant impact on productivity

Feature Category

CLI commands and flags

Use Case Example

_No response_

Additional Context

Repo: https://github.com/marolinik/MemoryForge
Version: 2.0.0 (3 hooks, 6 MCP tools, zero dependencies)
License: MIT