capture

Session Staging

Overview

Capture information from the current conversation into a staging file for the daily reflection pipeline to consume and write to the knowledge graph.

Core principles:

1. Token-conscious — 3-8 bullets, max 20 words each
2. Complementary to Stop hook — captures nuance and specificity the auto-summary misses
3. Append-only — never modify existing entries in the staging file
4. Confirm what was staged — always show the user exactly what was written

Argument Types

Argument	Behavior
(none)	Auto-extract 3-8 most important facts from the conversation
Specific text	Stage the provided facts as bullets
decisions	Extract only decisions made this session
technical	Extract only technical facts and implementation details

Workflow (MANDATORY — follow in order)

Step 1: Parse Input

Classify the argument:

• No argument → auto-extract mode
• Exactly the word decisions → filter to decisions only
• Exactly the word technical → filter to technical facts only
• Anything else → treat as specific facts provided by the user

Step 2: Resolve Staging File

Check in order:

1. scripts/session-staging.md in the project root (current working directory)
2. ~/.claude/session-staging.md as fallback

If the resolved file does not exist, create it with this header:

# Session Staging

Facts staged here are consumed by the daily reflection and written to the knowledge graph.

Step 3: Extract or Formulate Bullets

Based on argument type, produce 3-8 bullets. Each bullet: max 20 words, factual, specific.

Auto-extract (no argument): Scan the conversation for the most important facts — decisions made, technical details learned, status changes, new entities or tools introduced. Prefer concrete facts over vague summaries.

Specific facts (user-provided text): Convert the user's text into clean bullet points. If they already gave you bullets, clean and tighten them. If they gave you prose, extract the key facts.

decisions filter: Extract only explicit decisions made in this session — architectural choices, plans confirmed, approaches selected. Skip observations, status updates, and technical details.

technical filter: Extract only technical facts — implementation details, APIs used, data structures, file paths, commands, schemas, and configuration. Skip process, decisions, and context.

Get the current timestamp via Bash:

date '+%Y-%m-%d %H:%M'

Step 4: Append to Staging File

Use Bash with >> to append — do NOT use Write (overwrites the whole file) or Edit (find-replace, not true append):

{
  echo ""
  echo "## YYYY-MM-DD HH:MM"
  echo "<!-- source: manual -->"
  echo "- bullet 1"
  echo "- bullet 2"
} >> /path/to/staging-file.md

The <!-- source: manual --> marker tells the Stop hook that manual staging already happened today, enabling deduplication.

Step 5: Confirm

Display what was staged to the user. Show the exact bullets that were written. Keep it brief — no need to re-explain what staging does.

Scope Controls

• Max 8 bullets per entry
• Max 20 words per bullet
• Append-only — never modify existing entries
• Current conversation only — do not pull from memory, graph, or files

Common Mistakes

Mistake	Fix
Using Write or Edit to append	Write overwrites. Edit is find-replace, not append. Use Bash >>.
Exceeding 8 bullets	Pick the most important facts. Cut the rest.
Omitting <!-- source: manual -->	The Stop hook uses this marker for deduplication. Always include it.
Writing summaries instead of bullet facts	"Decided to use SQLite for storage" not "We had a productive discussion about databases."
Staging vague observations	"SQLite chosen over Postgres for local-first storage" not "database discussion happened."