Long-term persistence: a 20-line hook for memory-brain integrations

[Ashish-dwi99]

Summary

Adds an optional, filesystem-based extension point at ~/.gstack/hooks/ that lets any memory brain observe gstack's writes (learnings, timeline, checkpoints). Zero dependency on any specific brain. When no hook is installed, gstack behaves byte-identically to today.

The contract

Three hooks, all optional:

• ~/.gstack/hooks/on-learning-written — receives the validated JSON line on stdin after bin/gstack-learnings-log appends.
• ~/.gstack/hooks/on-timeline-written — same shape for bin/gstack-timeline-log.
• ~/.gstack/hooks/on-checkpoint-written — receives the checkpoint file path on stdin after context-save writes.

Properties:

• Optional — missing/non-executable hook = current behavior exactly.
• Non-blocking — backgrounded; a slow hook never slows a skill.
• Non-fatal — exit code ignored; a broken hook never breaks a skill.
• No injection surface — hook output is not piped back into gstack's workflow.

Why

docs/LONG_TERM_PERSISTENCE.md names six concrete spots where gstack's memory substrate leaks at the 1-year and 5-year horizon, each with a file:line citation — substring-only learnings search, no consolidation of near-dup keys, no correction loop, ls -t | head -3 checkpoint rehydration, no code world-model, honor-system cross-project trust. They're all fine at month three; they all bite at year five. The hook contract is the smallest change that lets anyone fix retrieval on top of gstack without gstack taking a dependency on any brain.

Disclosure

I'm the author of Dhee, which is one reference implementation of this hook contract. The contract itself is provider-neutral and MIT-licensed like the rest of gstack. I wrote the hook because I wanted Dhee to work cleanly with gstack, but the value is in the hook, not in Dhee — a different brain gets the same one-command install.

Files changed

• bin/gstack-learnings-log — 5 lines at end of happy path
• bin/gstack-timeline-log — 5 lines at end of happy path
• context-save/SKILL.md.tmpl — bash block + prose for on-checkpoint-written
• context-save/SKILL.md — regenerated via bun run gen:skill-docs --host all
• docs/adapters/README.md — hook payload spec
• docs/LONG_TERM_PERSISTENCE.md — the motivation essay

Happy for this to sit as an artifact

Merge would be great. Not merging is fine too. The hook contract works locally either way because ~/.gstack/hooks/ is filesystem-only. The goal is to name the place where gstack memory stops scaling and propose a contract small enough that it costs almost nothing to adopt.