How reflect captures + recalls across Claude Code and Codex CLI

Both Claude and Codex serialize the same JSON envelope onto the hook's stdin — {session_id, transcript_path, cwd, hook_event_name, source, ...}. The recall script is the same in both cases; the only thing that differs is which config file pointed the harness at it.

# the hook script reads from stdin
input = json.load(sys.stdin)
cwd = input.get('cwd')        # project being worked on
source = input.get('source')  # startup | resume | clear

The script doesn't ask the model "what do you need?" — it builds a context query itself from cheap signals: current working directory, current git branch, recent commit messages on the branch. That string becomes the GraphRAG query.

Two signals are blended: dense vector similarity over learning content, and graph proximity via entity sidecars (the .entities.yaml files written alongside each learning). Reranking weights recency, confidence tag, and tag overlap with the query. Output is capped at the top three.

The script emits a single JSON object on stdout containing hookSpecificOutput.additionalContext. The harness reads that envelope and silently prepends the learnings to the session's developer-message context — the user never sees the JSON, the model sees the learnings as if they were instructions.

{
  "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "additionalContext": "## Prior learnings relevant here\n- [lrn-...] Skill X must use ..."
  }
}

When the harness is about to compress history (because context is filling up), it serializes {session_id, transcript_path, trigger, ...} to the precompact hook. trigger is either auto (harness decided) or manual (user ran /compact).

The script appends a single line to ~/.reflect/pending_reflections.jsonl and returns immediately. No LLM call here. The queue file is shared across all harnesses — there's nothing claude-specific about it.

{"transcript_path": "...","session_id":"...","trigger":"auto","queued_at":"..."}

The next session that starts on this machine — Claude or Codex — fires reflect-drain-bg.sh as a detached background process ((nohup ... &) >/dev/null 2>&1) with a 5-second start budget. It's PID-locked so two concurrent drainers can't trample each other, and daily-capped via cost events so a runaway loop can't spend unlimited tokens.

For each queue entry, the drainer spawns claude -p "/reflect <transcript>" with --output-format json, --max-turns 25, and --permission-mode bypassPermissions. The /reflect skill scans the transcript, classifies corrections vs noteworthy patterns, and writes the resulting learning documents to ~/.learnings/documents/.

This subprocess is always claude, even when the queue entry was written by a codex session. Codex is the trigger, Claude is the worker. (Configurable via REFLECT_DRAIN_CLAUDE_BIN in environments where claude isn't on PATH.)

If at least one entry processed cleanly, the drainer runs reflect reindex (with a 5-minute timeout) so the GraphRAG index picks up the new .md + .entities.yaml files. Without this, learnings are still on disk — they just won't appear in future /recall results until a manual reindex.

Successful entries are removed from the queue; transient failures stay (with a retry counter); permanently broken entries (missing transcript, >3 retries) are moved to ~/.reflect/poison-reflections.jsonl.

Codex fires PreCompact → precompact_reflect.py appends one line to ~/.reflect/pending_reflections.jsonl with the codex transcript path. No reflection runs. Codex compacts and continues.

If another SessionStart in the same codex session had fired (e.g. on resume), it would have drained. But the user quit. The entry sits in the queue.

Claude fires SessionStart. Two hooks run: session_start_recall.py (injects whatever's already in the GraphRAG index — the codex morning's learnings are not there yet because they haven't been processed) and reflect-drain-bg.sh as a detached background process.

The drain script reads the queue, finds the morning's codex transcript path, and spawns claude -p "/reflect <morning-codex-transcript>" — note this is Claude processing a transcript that was produced by Codex. The transcript format is the same JSONL the harnesses use natively, so /reflect doesn't care which harness wrote it.

The headless run writes .md + .entities.yaml sidecars under ~/.learnings/documents/, then reflect reindex updates the GraphRAG index. The queue entry is removed.

From this point forward, the next SessionStart in any harness — including the very same Claude session that triggered the drain, on its next start — will see the morning's codex learnings in the top-3 if they match the cwd context.