.qe reads → DB: .qe/ content is stored in the SQLite store (qe_files), so a path may have no file on disk. Read .qe/ content with node scripts/qe-cat.mjs <path> (or --ls/--exists) and structured state with node scripts/qe-query.mjs … — do not assume the raw file exists. See QE_CONVENTIONS.md.

Qcompact — Context Preservation & Handoff

Role

A skill that automatically preserves context under context window pressure, and generates detailed handoff documents on user request.

Per-Session Layout (Auto-Named)

Multiple terminals on the same project save into separate sessions/{sid}/ directories so they never clobber each other. The 8-char sid is auto-derived from the Claude session id by the SessionStart hook and surfaced as [Session] sid:XXXXXXXX in additionalContext — there is no manual --name flag. When no sid is available the _unknown bucket is used; pre-partition flat files were one-shot migrated into _legacy.

SessionStart may also surface [Session State] ... with the active plan, resume source, and Codex background job status. Treat that line as an advisory shortcut only; the resolver functions below remain the source of truth.

Operating Modes

Automatic Mode (Background Call)

Ecompact-executor detects context pressure and runs automatically in the background.

• Saves quietly without notifying the user
• Triggered when entering the CONTEXT_BUDGET.md warning zone (70%+ of the active context window by default)
• Saves current state to .qe/context/sessions/{sid}/snapshot.md
• Accumulates decisions in .qe/context/sessions/{sid}/decisions.md

Manual Mode (User Invocation)

Calling {adapter.commandPrefix}Qcompact directly generates a detailed handoff document.

• Delegates mode=handoff to Ecompact-executor
• Creates .qe/handoffs/sessions/{sid}/HANDOFF_{date}_{time}.md
• Displays saved context + handoff summary to the user

---

Automatic Mode Details

Save Location

.qe/context/sessions/{sid}/ (auto-named per Claude session)

Saved Content

snapshot.md — Context Snapshot

Overwritten on each save (only the latest state is retained):

# Context Snapshot
> Saved at: 2026-03-14 10:30

## Current Task
- In-progress task UUID and title
- Checklist progress (completed/total)
- Checklist item currently being worked on

## Key Decisions
- Major decisions made this session
- Directions explicitly instructed by the user

## Changed Files
- Files created/modified/deleted this session

## Pending Items
- Work not yet finished
- What to do next

## Notes
- Constraints or requirements to remember specifically

decisions.md — Accumulated Decision History

Accumulated per session (reverse order, newest first):

## [2026-03-14] Session
- Decided to separate framework data into .qe/ folder
- Changed agent prefix from A → E
- Branded as QE framework (Query Executor)

---

Manual Mode Details

CREATE Workflow

Step 1: Delegate to Ecompact-executor

Call Ecompact-executor with a complete delegation packet and mode=handoff.

• Create .qe/handoffs/ directory (if not present)
• Create HANDOFF_{date}_{time}.md file
• Auto-collect current task state, git changes, and decisions

Step 2: Write Handoff Document

1. Current status summary — what the situation is right now
2. Important context — key information the next agent must know
3. Immediate next steps — clear, actionable first step
4. Decisions — choices that include not just the outcome but the reason

Step 3: Verify

• No [TODO: ...] placeholders remain
• Required sections exist and are filled in
• No potentially confidential information (API keys, passwords, tokens)
• Referenced files exist
• Rebuild the derived index once — node scripts/lib/doc-index.mjs (single scan-based rebuild; never append to .qe/index.md). See core/DOC_CONVENTIONS.md.

Step 4: Report to User

• Handoff file location
• Summary of captured context
• First action item for the next session

RESUME Workflow

Step 1: Look Up Handoff

Use the shared resolver — resolveResumeContext(projectRoot, overrideSid) in hooks/scripts/lib/session-resolver.mjs — the same function {adapter.commandPrefix}Qresume uses, so handoff lookup here and restore there cannot diverge. It scans the active sid across both .qe/context/ and .qe/handoffs/ first, and when the active sid is empty in both, falls back to the newest other bucket (durable handoffs are unioned in, so a handoff saved under a prior sid is reachable). Read latestHandoff from the returned descriptor; when source: 'fallback', tell the user which bucket was loaded.

On Codex, render the same workflow as $Qresume / $Qresume --from {sid} in handoffs. Do not emit Claude-only slash commands in Codex-facing text.

Step 2: Check Freshness

Level	Meaning
FRESH	Safe to resume — minimal changes
SLIGHTLY_STALE	Review changes before resuming
STALE	Carefully verify context
VERY_STALE	Consider creating a new handoff

Step 3: Load Handoff and Start Work

• Read the handoff document and start from item #1 of "Immediate next steps"
• If there are chained handoffs, also reference previous ones

Handoff Chaining

In long-running projects, link handoffs to each other to maintain context lineage:

HANDOFF_1.md → HANDOFF_2.md → HANDOFF_3.md

---

Save Location Summary

Mode	Location	Purpose
Automatic	.qe/context/sessions/{sid}/snapshot.md	Latest context for this terminal (overwrite)
Automatic	.qe/context/sessions/{sid}/decisions.md	Accumulated decisions for this terminal
Manual	.qe/handoffs/sessions/{sid}/HANDOFF_*.md	Detailed handoff document for this terminal

Will

• Automatic: save context snapshot, accumulate decisions
• Manual: generate detailed handoff document, verify, chain
• Delegate to Ecompact-executor (automatic)
• Delegate to Ecompact-executor (manual handoff)

Will Not

• Save entire conversation (extract key points only)
• Copy entire code (record file paths only)
• Notify user (during automatic execution)
• Include confidential information