Suggestion: optional delta hook on SessionStore

[ketankhairnar]

Suggestion: optional delta hook on SessionStore

What I noticed

While drafting persistence guides for Postgres and D1, I went looking at how other coding-agent CLIs persist sessions to see if there were patterns worth lifting. Three independent implementations have landed on the same shape — append-only event log + queryable index:

Tool	Storage shape
Claude Code	~/.claude/projects/<project>/<sessionId>.jsonl — one line per event, append-only. Sidecar .meta.json and .session-intelligence.json.
Codex CLI (deepwiki)	JSONL events + SQLite index for resumption / forking.
OpenCode 1.2+ (deepwiki)	Migrated from per-session JSON files to centralized SQLite. Dual-layer: SQLite for queryable rows + filesystem for large unstructured payloads.

The thread that runs through all three: don't rewrite the whole conversation history every turn. Append the delta. Read by reconstructing.

How this maps to flue

Flue's data model is already append-friendly — SessionEntry has stable id, immutable parentId, and compaction creates new entries pointing back at a firstKeptEntryId rather than mutating prior ones. The bit that doesn't fit the append model is the store interface:

export interface SessionStore {
  save(id: string, data: SessionData): Promise<void>;
  load(id: string): Promise<SessionData | null>;
  delete(id: string): Promise<void>;
}

save() is blob-overwrite — every turn, the adapter receives the entire SessionData and is expected to persist all of it. For a 50-turn coding-agent session with embedded tool results, that's hundreds of KB rewritten on every save.

Concretely, the Option 2 schema referenced in the new persistence guides (the append-log shape Claude Code / Codex / OpenCode use) currently has to:

1. Accept the full SessionData from save().
2. Pull the existing entry IDs from the DB.
3. Diff to find what's new.
4. Write only the delta.

That diff cost is paid by every adapter, and the interface gives the adapter no signal about what changed. Worst case: a session where compaction replaced recent entries with a summary; the adapter has to detect that the prior entries should be marked superseded.

For discussion: a small, opt-in delta hook

Extend SessionStore with an optional method that, when present, is called instead of save() with just what's new:

export interface SessionStore {
  save(id: string, data: SessionData): Promise<void>;
  load(id: string): Promise<SessionData | null>;
  delete(id: string): Promise<void>;

  /**
   * If implemented, called instead of save() with only the entries new
   * since the last save and any metadata/leafId changes. Adapters that
   * implement this can persist O(delta) instead of O(history) per turn.
   */
  saveDelta?(id: string, delta: SessionDelta): Promise<void>;
}

export interface SessionDelta {
  newEntries: SessionEntry[];      // appended since the last save
  leafId: string | null;           // current leaf
  metadata: Record<string, any>;   // current metadata (full overwrite is fine)
  supersedes?: string[];           // entry IDs marked superseded (compaction)
}

Properties of this shape:

• Non-breaking. Existing save() keeps working. InMemorySessionStore, the Cloudflare DO store, and the new Postgres/D1 recipes need zero changes.
• Opt-in. Adapters implement the hook only if they want delta semantics.
• Small SDK change. Flue already tracks the delta as it builds SessionData — it knows what it just appended. Probably <50 lines in session.ts to thread it through.
• Forward-compatible. If a future bigger revision of the interface ever lands, this hook is a strict subset of any plausible entry-level API.

(A larger reshape — a fully entry-level interface with appendEntries / loadEntries instead of save/load — is also possible but bigger; mentioning for completeness, not advocating.)

What I'd want to know

Is this directionally interesting, or does the blob-overwrite shape stay because of constraints I'm missing (e.g. something about compaction's firstKeptEntryId pointer or branch-summary entries that doesn't fit the delta model cleanly)? Happy to draft a PR if so, or back off if not.

[FredKSchott]

this makes a ton of sense to me, definitely directionally interesting.

We designed our message format with this in mind, where compaction doesn't overwrite the message conversation history and instead just appends a "compaction point" in the conversation history, preserving the original history.

I'd love for this layer to be more pluggable, similar to how we do sandboxes. If we could create a session persistence API that any DB/storage solution could hook into, that would be great. flue add postgres, flue add redis, etc.

While drafting persistence guides for Postgres and D1,

FYI If you're on Cloudflare, you should be getting persistence already out of the box, thanks to Durable Objects and D1.

[ketankhairnar]

Thanks Fred — the "compaction as append point, not overwrite" detail is exactly the constraint I was hoping someone with the design history would confirm. That makes Option A (the optional saveDelta hook) clean — no special case for compaction, the supersedes field on SessionDelta covers it.

If we could create a session persistence API that any DB/storage solution could hook into, that would be great. flue add postgres, flue add redis, etc.

Strong +1, and that's the right shape. I'd been holding back on a category: "persist" for connectors/ because the README explicitly says "please don't open PRs introducing new categories" — your comment reads as the green light to do exactly that.

Two ways to thread this:

1. Repurpose PR #87 (the Postgres + D1 docs I opened earlier today) — convert the docs into connectors/persist--postgres.md and connectors/persist--d1.md, add "persist" as a recognized category, wire it through flue add. Roughly the same diff, restructured.
2. Keep docs: add Postgres + D1 session persistence guides #87 as docs-only, file a separate PR for the category + CLI wiring. Cleaner separation, slower delivery.

I'm fine with either — leaning toward (1) since the docs and the category land most naturally together. Will comment on the PR with the same question so the conversation has a single home.

FYI If you're on Cloudflare, you should be getting persistence already out of the box, thanks to Durable Objects and D1.

Quick fact-check: Durable Objects yes (the generated Cloudflare entry uses ctx.storage.sql automatically — this part works great). D1 isn't wired in by default though — there's no D1 binding in the merged wrangler.jsonc, no D1-backed SessionStore in cloudflare/session-store.ts or the build plugin. The persist-d1.md guide I drafted is the first D1 integration, framed as an opt-in alternative for sessions queryable from a separate Worker / admin tooling. Happy to be wrong if I'm reading the source incorrectly.

[ketankhairnar]

Closing the loop on this one. PR #87 shipped the connector restructure (Postgres + D1 recipes as category: "persist"). The SDK-side saveDelta? hook proposed in the OP is now up as PR #95 — minimal addition to SessionStore ({ newEntries, leafId, metadata }, no supersedes for v1 since appendCompaction is already append-only), non-breaking, falls through to save(full) when the adapter doesn't implement it.

Tests deferred to a follow-up after the in-flight feat/test-infra work lands on main — noted in PR #95's description.

[astrobot-houston]

Possibly related contribution from @ketankhairnar — opened #95 which appears to be addressing this.

Their summary: Adds an optional saveDelta? method to the SessionStore interface along with a SessionDelta type, allowing persistence adapters to write only newly appended entries per turn (O(delta)) instead of the full session history (O(history)). The SDK tracks the last saved entry count and automatically routes through the delta path when the adapter implements it, falling back to the existing full-save path otherwise.

Implementation: ketankhairnar/flue@feat/sdk-savedelta-hook (diff)

This comment was posted automatically when #95 was redirected. The implementation is preserved on the branch above so it can inform the work here.