WAYS OF WORKING · APPLIED NINO CHAVEZ
Close the session.
Keep the lesson.
Raw agent transcripts are working evidence, not permanent memory. Before archiving, move project truth into its owning repository, keep a small searchable residue, and say plainly when the raw record is not safe to delete.
closeout receipt
Outcome · canonical updates · verified evidence · still unproven · next action · recall recipe · archive-safe: yes/no
The final field is a judgment, not a database status.
→ or scroll to advance · ← to go back
02 THE PROBLEM
The archive is carrying four different jobs
A transcript mixes decisions, evidence, reusable technique, and disposable chronology. Keeping the whole file preserves all four, but makes storage and retrieval worse. Deleting it blindly can erase the only copy of a decision.
The compact store made 605 Codex transcripts searchable. That proved ingestion. It did not prove that every project-specific lesson had moved somewhere durable, so raw deletion stayed blocked.
03 WHAT SURVIVES
Promote meaning before compressing history
Sort the session into four destinations. This is the semantic work a generic transcript miner cannot do for you.
PROJECT TRUTH → owning repo: decision, rule, status, next action VERIFIED EVIDENCE→ tests, receipts, revisions, measured results REUSABLE METHOD → a small skill, recipe, or searchable signal CHRONOLOGY → raw transcript; retain only while it still carries value
Do not turn an agent inference into a project decision. Do not write secrets or private transcripts into a shared recipe. Do not call a human review complete because an agent summarized it.
04 THE RECEIPT
Make archive safety an explicit claim
A closeout receipt gives the next session a compact restart point and makes missing judgment visible.
CLOSEOUT_COMPLETE Outcome: cross-client retention pipeline installed Canonical updates: docs/session-retention.md Verified evidence: parser fixtures and database check passed Still unproven: old transcripts may contain unpromoted project detail Next action: review the archive after the grace window Recall recipe: session-retention-v1 Archive-safe: no
Archive-safe: no is a successful result. It says the closeout found a real gap instead of hiding it behind a green ingestion check.
05 THE AUTOMATION
Keep the lifecycle hook boring
Turn-ending hooks have short operational budgets. Their job is to record identity and return — not parse a long transcript, update several indexes, or recursively delete files.
SessionEnd → append { client, task_id, path, cwd } → return ↓ worker → normalize → mine → transact → watermark ↓ policy → grace window + closeout + explicit deletion
For Codex, review the exact command through /hooks. New or changed command hooks require trust, and SessionEnd allows at most three seconds. Trust is a safety boundary, not a startup nuisance to bypass.
06 PROVENANCE
A small memory still needs a chain of custody
Different clients write different JSONL shapes. Normalize them at one boundary, and keep enough source identity to audit every retained signal.
Normalize verified prose only
Map client events into timestamp, role, phase, text. Fixtures should prove that injected instructions, tool output, and summaries do not become user preferences or assistant examples.
Watermark after commit
Store source client, canonical task identity, project path, and timestamp. Bind the watermark to transcript path plus modification time, and advance it only after the database transaction commits.A current watermark proves ingestion, not semantic completeness.
07 A SEPARATE CLEANUP LOOP
Build artifacts are not session memory
Prove the candidate
Enumerate with git worktree list. Exclude the main checkout. Require the candidate path to be ignored and require git ls-files to find no tracked descendants.
Prove nobody is using it
Recognize live sessions from every supported client. Directory modification time is not enough: editing an existing file may not update the worktree root. Recheck liveness immediately before deletion.
Prove the execution shape
Ship report-only first. Enqueue long cleanup work. Recheck every gate just before removal. Never use force for worktree deletion.A successful deletion does not prove the safety model.
08 USE IT
Close one real session before automating deletion
1 · Promote
Move decisions, current status, verified evidence, and the next action into the repository or system that owns them. Link instead of duplicating.
2 · Distill
Save a small recipe only when the method will recur. Keep provenance attached. Name uncertainty instead of compressing it into a confident summary.
3 · Decide
Issue the closeout receipt. Keep the transcript through a grace window. Delete only when the closeout says yes and the ingestion watermark is current.