feat(session): add anti-drift session notes

[vicary]

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.

[Copilot]

Pull request overview

This PR advances the “search-first unified memory” architecture by introducing normalized memory result contracts, durable session notes (no TTL) with freshness-aware ranking, and a new <memory version="2"> injection envelope that avoids injecting exact <entry> records. It also adds dream summary storage/job scaffolding and extends shutdown/teardown coverage to prove graceful waiting behavior.

Changes:

• Introduces normalized memory result models and a unified session_search() orchestration path that can merge entries/notes/summaries.
• Adds durable session notes (no TTL), note read metadata (last_read_at), freshness-based ranking, and MCP note read/write tools.
• Updates continuity injection to <memory version="2"> (nested <persistent_memory> and optional compaction-only <session_notes>), plus adds shutdown warning/proof scaffolding.

Reviewed changes

Copilot reviewed 47 out of 48 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
src/types/index.ts	Adds NormalizedMemoryResult contract for unified memory search/injection.
src/testing/detached-dream-proof.ts	Adds proof-only plugin to validate graceful shutdown waiting behavior.
src/testing/detached-dream-proof.test.ts	Tests detached dream proof plugin behavior/artifact writing.
src/session.ts	Updates injection envelope to <memory version="2">, strips <entry> blocks, adds compaction-only note injection.
src/session.test.ts	Adds tests for compaction notes injection and v2 envelope invariants.
src/services/session-snapshot.test.ts	Updates expectations to <memory version="2">.
src/services/session-notes.ts	Introduces durable session notes service with freshness-aware search and same-project delete-by-id semantics.
src/services/session-mcp-types.ts	Extends MCP schemas: normalized search results (ref/refs) and note tool request/response types.
src/services/session-mcp-runtime.ts	Wires session_search through unified memory search, adds note tools + descriptions, increases response budget.
src/services/runtime-teardown.ts	Adds createRuntimeTeardownTask helper and refines Deno vs Node signal listener wiring.
src/services/runtime-teardown.test.ts	Adds “live runtime” shutdown-wait proofs for SIGINT and beforeExit flows.
src/services/redis-snapshot.ts	Adds helper to emit snapshot summaries as NormalizedMemoryResult.
src/services/redis-client.test.ts	Makes waitFor async-friendly to reduce flakiness.
src/services/opencode-warning.ts	Adds notifyDreamShutdownDelay() warning helper.
src/services/memory-search.ts	Adds unified memory search service (entries + notes + summaries) with query vs reflection mode behavior.
src/services/memory-search.test.ts	Tests ordering and query/reflection mode behavior for unified memory search.
src/services/memory-results.ts	Adds ordering utilities for normalized memory results.
src/services/hot-tier-slice.test.ts	Updates continuity assertions for <memory version="2"> envelope.
src/services/exact-history.ts	Adds adapter interface/scaffold for exact-history searching.
src/services/dream-store.ts	Adds Redis-backed dream summary storage + retrieval around a reference time.
src/services/dream-runner.ts	Adds dream runner that buckets inputs and advances watermark.
src/services/dream-runner.test.ts	Tests dream store + runner watermark/summary behavior.
src/services/dream-jobs.ts	Adds pending dream job storage/preparation.
src/services/dream-jobs.test.ts	Tests dream job write/read/clear and prepare semantics.
src/services/detached-dream-worker.ts	Adds detached worker spawn scaffold (currently returns false).
src/index.ts	Wires notes service into runtime/session manager; adds session_search biasing and dream shutdown warning teardown task.
src/index.test.ts	Extends entrypoint tests for notes service wiring, biasing, dream shutdown warning behavior, and tool arg exposure.
src/handlers/tool-before.ts	Uses deny guidance as the thrown error message when present.
src/handlers/tool-before.test.ts	Updates tests to assert new thrown-denial guidance behavior.
src/handlers/messages.ts	Updates scrubbing logic for the new <memory> envelope and logging text.
src/handlers/messages.test.ts	Updates tests for <memory version="2"> injection and scrubbing behavior.
src/handlers/compacting.ts	Passes { forCompaction: true } to inject compaction-only session notes and updates log messages.
src/handlers/compacting.test.ts	Updates compaction tests for v2 envelope and compaction options.
src/handlers/chat.ts	Updates log messages to “memory” naming.
src/handlers/chat.test.ts	Updates chat handler tests for new prepareInjection signature.
opencode.json	Removes local dev plugin config from repo root.
docs/superpowers/specs/2026-05-10-session-notes-freshness-without-ttl-design.md	Adds design doc for durable notes and freshness ranking.
docs/superpowers/specs/2026-04-21-search-first-unified-memory-design.md	Adds design doc for search-first unified memory architecture.
docs/superpowers/specs/2026-04-11-session-notes-anti-drift-design.md	Adds spec doc for cross-session notes recall model.
docs/superpowers/plans/2026-05-10-session-notes-freshness-without-ttl.md	Adds implementation plan for durable notes + freshness ranking.
docs/superpowers/plans/2026-03-20-context-mode-mcp-first-implementation.md	Updates bounded-response budget documentation to 32 KB.
docs/SmokeTests.md	Updates smoke-test coverage and procedures for notes/tools and dream shutdown proof.
deno.lock	Adds @std/async dependency lock entry.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 52 out of 53 changed files in this pull request and generated 6 comments.

[Copilot]

Pull request overview

Copilot reviewed 55 out of 56 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 59 out of 60 changed files in this pull request and generated 2 comments.

Comments suppressed due to low confidence (1)

src/session.ts:596

• PR description/design docs describe the new injection envelope as a normalized hint surface (summaries + optional notes, with exact entries excluded). However, buildPreparedInjectionEnvelope still emits the legacy event-projection sections (<last_request>, <active_tasks>, <key_decisions>, <files_in_play>, etc.). Either the PR description/docs need to be adjusted to reflect this interim shape, or the envelope builder should be updated to only render normalized note/summary-derived tags.