Plan + ADR for channel-memory capability and digest-backed channel-awareness (issue #232 Phase 2)

[mostlydev]

Summary

This PR fills in the design surface for issue #232 Phase 2 without starting implementation.

It adds:

• a channel-memory adapter plan for digest-backed channel-awareness
• a Phase 2 pointer in the existing cllama: guarantee bounded 24h channel awareness independent of cursors and restarts #232 channel-awareness plan
• ADR-025 for the new channel-memory capability boundary and raw_window+digest awareness model

Design Shape

The plan keeps the existing #232 surfaces rather than creating a new feed:

• channel-awareness remains the provider-visible awareness feed
• raw_window+digest becomes the Phase 2 context kind
• claw-wall owns Discord ingest, message identity, ACL checks, and feed serving
• channel-memory owns durable channel-message retention, deterministic processing, async LLM digest generation, tombstones, and provenance
• cllama owns provider-visible injection, feed budgets, retrieval mediation, and channel_context_op telemetry

Storage And Recall

The plan now requires an indexed durable store for v1, with SQLite as the recommended embedded database. Raw source messages and sparse summaries are not parallel histories: sparse recall blocks are derived rows over retained source-message ranges, with many-to-many provenance back to exact messages.

That allows recent recall to stay detailed while older channel exchanges can compact into sparse topic_rollup or sequence_rollup blocks.

Prerequisite

Digest-backed awareness depends on a tight #232 Phase 1 follow-up: channel-awareness and the retrieval tools must expose stable Discord message IDs, or equivalent stable source handles, so digest provenance can round-trip to exact source messages.

Validation

Docs-only change. Validated with:

• git diff --check

Refs #232.

[mostlydev]

Purpose and scope (for implementers)

This is design-only. Before anyone writes code against it, here is the intent and the boundaries so the implementation lands correctly.

Why this exists

This came out of a live incident on a downstream real-money trading desk. Agents there wake cold every turn and share a Discord trading floor as their only common reality. The provider-visible prompt began hitting the ~120s request envelope and timing out. Investigation showed the size driver was the raw 24h channel-awareness window (~90KB, ~200 messages on the sampled turn), not feed-fetch latency — fetches completed quickly, the model/provider path expired.

The critical finding: the bytes were mostly substantive agent decision content, not telemetry noise. So this is not fixable by truncation or by stripping status lines alone. We need to keep recent floor reality at high resolution while compacting older material, and never drop the exact messages where trading decisions were made.

Product goal: retention and recall as first-class

The target model is "high-resolution recent, compact older, exact-source retrievable." Retention (a durable source-of-truth for channel messages) and recall (compact, decision-relevant, provenance-backed) are the actual goals — not byte reduction for its own sake. A 90% smaller feed that drops a fill report, a stop change, or a routing decision is a failure, not a success.

The load-bearing invariant

Sparse/digest blocks are derived artifacts over retained source messages, never a parallel primary history that can diverge. This mirrors ADR-018 (raw ledger stays authoritative) and #164 salience-memory (raw session ledger stays authoritative outside the adapter). If you find yourself building a sparse/digest table that becomes the source of truth for older content, stop — that divergence is exactly what this design exists to prevent. Source messages are authoritative; digest rows point back to them with many-to-many provenance and are recomputed/tombstoned when sources change.

In scope (this PR)

• the channel-memory capability boundary (ADR-025): claw-wall owns Discord ingest + identity + ACL + serving; channel-memory owns durable retention + processing + digest; cllama owns injection + telemetry
• digest-backed channel-awareness reusing the existing feed with the reserved raw_window+digest context kind
• async-LLM / sync-recall processing (reuse Salience-memory adapter for derived recall blocks #164's pattern — never inline an LLM in feed serving; that just moves the timeout from the provider call into feed assembly)
• a deterministic-without-LLM mode as both the test harness and the safety fallback
• provenance + retrieval through the existing search_channel_context / get_channel_messages tools

Out of scope (do not start here)

• implementation (examples/channel-memory comes after design approval, promoted to a published image only after it proves out — same model as Salience-memory adapter for derived recall blocks #164)
• changing any downstream pod's feed subscriptions (that is a later, separately-approved rollout with its own ADR on the consumer side)
• introducing a new feed surface (reuse channel-awareness)
• forcing channel-memory into the existing memory capability — it is channel-shaped (shared room state, recalled via channel-awareness, ACL'd by channel allowlist), not per-agent session-shaped

Hard prerequisite

Digest provenance cannot round-trip without stable Discord message IDs (or an equivalent stable source handle) in channel-awareness lines and retrieval-tool results. Timestamp-only references break on chunked reports and same-minute multi-author bursts. This is a tight, separately-scoped #232 Phase 1 follow-up and a blocker for trustworthy digests.

What "done" looks like for a first cut

• feed serving never calls an LLM
• deterministic mode works with no LLM key
• hard events (trade proposal / approval / confirmation / fill, stop/target change, explicit route/no-route, risk-limit) preserved verbatim or near-verbatim
• edits / deletes / forgets propagate to derived blocks via dirty markers + tombstones
• coverage gaps and stale digests are explicit in the feed header
• after async LLM rollup, meaningful byte reduction on a busy-channel sample with zero missed hard events

The downstream desk will supply sanitized real busy-window captures as acceptance evidence once an implementation exists.

Two small clarifications worth folding into the plan

1. source_messages is keyed including content_hash, so an edited message creates a new row (edit history is retained). Add one line confirming the recall/serving path selects the current version, not a superseded one.
2. Define the sparse flag explicitly: sparse=true means the block summarizes/omits source content; sparse=false means it reproduces source faithfully (e.g. hard_event, raw_excerpt). Otherwise "sparse raw_excerpt" is ambiguous.

[mostlydev]

Folded the two provenance clarifications into the plan/ADR in f01155c: current non-deleted source version selection after edits, and explicit sparse=true/false content-fidelity semantics.\n\nI also opened the prerequisite implementation issue (#263) and draft PR #264 for stable channel source handles. #264 intentionally stays below the channel-memory adapter boundary: it only makes current claw-wall awareness/retrieval source-backed enough for the digest work to build on.

[mostlydev]

Execution follow-up status:

• stable source handles prerequisite landed in Expose stable source handles in channel awareness #264 and closed claw-wall: expose stable source handles in channel awareness #263
• content-hash/edit identity is documented as deferred to the adapter phase on claw-wall: expose stable source handles in channel awareness #263
• Phase 2 implementation has been split into Ready roadmap issues: channel-memory: add SQLite source-message adapter #265 (SQLite source-message adapter), claw-wall: push channel messages into channel-memory #266 (claw-wall push ingest), channel-awareness: serve raw_window+digest from channel-memory #267 (raw_window+digest serving + telemetry), channel-memory: add async LLM digest worker and cost caps #268 (async LLM digest worker + cost caps)
• scrubbed the new plan examples so the public design stays deployment-agnostic

Leaving this as the design/ADR PR; the implementation work is now tracked in the follow-up issues above.