Skip to content

feat(session): add anti-drift session notes#7

Open
vicary wants to merge 4 commits intomainfrom
feat/session-notes-anti-drift
Open

feat(session): add anti-drift session notes#7
vicary wants to merge 4 commits intomainfrom
feat/session-notes-anti-drift

Conversation

@vicary
Copy link
Copy Markdown
Owner

@vicary vicary commented Apr 11, 2026

Summary

  • Redesign memory around a search-first architecture where session_search() is the canonical recall API and injected XML is only a bounded hint surface.
  • Add durable session notes without TTL, freshness-aware note ranking, timestamped note hits, and same-project delete-by-id cleanup.
  • Introduce normalized memory result contracts, dream summary storage/job scaffolding, detached shutdown proof coverage, and updated smoke-test documentation for the new model.

Design

Authority Model

  • opencode db / SQLite is the exact chronological source of truth for user turns, assistant turns, and tool calls.
  • Redis/FalkorDB stores derived local artifacts and operational state, not duplicate exact transcript authority.
  • Graphiti remains asynchronous enrichment and a one-off hint source; it is not on the hot path and is not the authoritative memory reader.

Canonical Recall Path

  • session_search() becomes the default memory read API.
  • Query mode accepts query plus optional when, searches normalized exact/history, notes, and summaries, and returns exact-style results before summaries.
  • Reflection mode is represented by an empty query and returns chronological summaries around when.
  • Results use a shared normalized model with type: "entry" | "note" | "summary", ref, snippet, score, created_at, and optional metadata.

Injection Contract

  • Injected continuity now uses one top-level <memory version="2"> wrapper.
  • <persistent_memory> is nested inside <memory> instead of being a separate top-level block.
  • Exact entries are never injected; exact recall must go through session_search().
  • Compaction/startup continuity may include bounded summaries and up to 10 current-session notes, but not raw exact entries.
  • Legacy <session_memory> expectations were updated in tests to the normalized <memory> envelope.

Durable Session Notes

  • Session-local note hashes no longer receive TTLs, and reads no longer refresh note TTL.
  • Project note metadata now records last_read_at on successful session_notes_read(id) calls.
  • session_search note hits expose created_at and updated_at, but not last_read_at.
  • Note ranking now uses relevance multiplied by write freshness and bounded read freshness.
  • Same-project sessions may delete obsolete notes by id, while non-empty replacement remains ownership-conservative.

Dream Summary Layer

  • Adds local dream summary/job scaffolding for durable summary artifacts.
  • Dream summaries are intended as lossy chronological hints for reflection and injection, not exact transcript truth.
  • Shutdown handoff now has proof-only detached worker coverage plus explicit warning fallback behavior when detached work cannot be started safely.

Graphiti Role

  • Graphiti remains optional and asynchronous.
  • Graphiti-derived material is treated as hint-only summary material.
  • If a Graphiti hint matters, agents should reconnect to exact evidence through session_search().

Retention Model

  • Durable memory artifacts such as notes and summaries do not expire by TTL.
  • Operational state remains bounded separately.
  • Staleness is handled by ranking and relevance rather than deleting useful memory by age.

Implementation Notes

  • Added normalized memory result types and memory-search orchestration.
  • Updated session_search schemas and runtime wiring for normalized ref / refs responses and optional when.
  • Updated note storage, note search, note read metadata, note delete semantics, and entrypoint wiring.
  • Updated message/compaction scrubbing and assertions for the <memory version="2"> wrapper.
  • Added dream store, dream runner, dream job, detached-worker proof, and shutdown warning coverage.
  • Updated smoke tests and design/implementation docs for the search-first unified memory direction.

Test Plan

  • deno test -A
  • deno task check
  • deno task lint
  • deno task fmt --check

Latest full-suite verification before commit: 66 passed (692 steps), 0 failed.

@vicary vicary force-pushed the feat/session-notes-anti-drift branch from ff69c1e to cfac4be Compare May 10, 2026 12:53
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant