From a7052751e4f7a1d393ba37d4d686b338b800c0c1 Mon Sep 17 00:00:00 2001 From: Hunter Bown Date: Fri, 5 Jun 2026 23:18:34 -0700 Subject: [PATCH] docs(whaleflow): define external memory cutline (#2842) --- CHANGELOG.md | 3 ++ crates/tui/CHANGELOG.md | 3 ++ docs/VISION_NORTH_STAR.md | 4 +- docs/WHALEFLOW_EXTERNAL_MEMORY.md | 72 +++++++++++++++++++++++++++++++ 4 files changed, 81 insertions(+), 1 deletion(-) create mode 100644 docs/WHALEFLOW_EXTERNAL_MEMORY.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 2e3be691..172c3500 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -89,6 +89,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 stored on teacher candidates, and a deterministic PromotionGate compares baseline-vs-candidate replay deltas, required tests, policy violations, staleness, and cost constraints before marking a candidate promotable (#2675). + The external-memory cutline now documents that Aleph-style memory stays + optional, explicit, visible, and clear/export-capable for v0.9.0 rather than + becoming a hidden default context substrate (#2677). Thanks @AdityaVG13 for the WhaleFlow draft and cost-tracking direction. - Added a state-store v2 schema migration for WhaleFlow trace tables covering workflow, branch, leaf, control-node, and teacher-candidate runs. The diff --git a/crates/tui/CHANGELOG.md b/crates/tui/CHANGELOG.md index 2e3be691..172c3500 100644 --- a/crates/tui/CHANGELOG.md +++ b/crates/tui/CHANGELOG.md @@ -89,6 +89,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 stored on teacher candidates, and a deterministic PromotionGate compares baseline-vs-candidate replay deltas, required tests, policy violations, staleness, and cost constraints before marking a candidate promotable (#2675). + The external-memory cutline now documents that Aleph-style memory stays + optional, explicit, visible, and clear/export-capable for v0.9.0 rather than + becoming a hidden default context substrate (#2677). Thanks @AdityaVG13 for the WhaleFlow draft and cost-tracking direction. - Added a state-store v2 schema migration for WhaleFlow trace tables covering workflow, branch, leaf, control-node, and teacher-candidate runs. The diff --git a/docs/VISION_NORTH_STAR.md b/docs/VISION_NORTH_STAR.md index 064d8885..0c88ae3c 100644 --- a/docs/VISION_NORTH_STAR.md +++ b/docs/VISION_NORTH_STAR.md @@ -280,7 +280,9 @@ clearable, and scoped**: `finalize`/`FINAL` is an *in-kernel Python function*, not a tool). 6. **Cached-main overlay** โ€” promoted lessons from the cached main branch (`/overlay`, ยง9). -7. **External memory (Aleph)** โ€” large local data via the `aleph` skill. +7. **External memory (Aleph)** โ€” large local data via the `aleph` skill; + see `docs/WHALEFLOW_EXTERNAL_MEMORY.md` for the v0.9.0 cutline that keeps + this optional, explicit, inspectable, and out of the default path. **Why it helps weaker models.** The model never has to *guess* where a fact should live or *re-derive* context it already established. Each layer has a diff --git a/docs/WHALEFLOW_EXTERNAL_MEMORY.md b/docs/WHALEFLOW_EXTERNAL_MEMORY.md new file mode 100644 index 00000000..608eeade --- /dev/null +++ b/docs/WHALEFLOW_EXTERNAL_MEMORY.md @@ -0,0 +1,72 @@ +# WhaleFlow External Memory Cutline + +This note resolves the v0.9.0 cutline for Aleph-style external memory in +WhaleFlow. It is a design boundary, not a runtime implementation. + +## Decision + +External memory should be optional and explicit for v0.9.0. Normal CodeWhale +operation must not depend on it, and WhaleFlow must not silently enable it for +long-running runs. + +For v0.9.0, external memory can appear only as: + +- an explicit workflow node whose inputs, outputs, scope, and permissions are + visible in the typed WhaleFlow IR; +- an optional plugin or skill-backed tool that the user enables deliberately; +- a documented experiment whose state can be inspected, cleared, and exported. + +It should not be a hidden context substrate, a replacement for repo search, or a +default backing store for every workflow run. + +## Layer Boundaries + +External memory is separate from the existing memory and replay layers: + +| Layer | Scope | v0.9.0 rule | +| --- | --- | --- | +| User memory | Small durable user preferences and facts surfaced by `/memory` | Opt-in, user-owned, not workflow evidence | +| Repo search / codemap | Derived repo structure and search results | Rebuildable from the workspace; not a memory log | +| ARMH/RLM memo | In-session working memory and exact-context memoization | Visible hit/miss telemetry; not durable replay evidence | +| TraceStore | Recorded workflow, branch, leaf, and control results | Source of deterministic replay; no live model calls during replay | +| Cached-main overlay | Promoted lessons after review and replay | Inspectable and reversible; never mutates Git main | +| External memory | Large local or plugin-backed data outside normal context | Explicit node/plugin only; visible state and clear/export required | + +## Visibility Requirements + +Any future external-memory implementation must show: + +- when it is active; +- which workflow node or plugin owns it; +- where its state is stored; +- what repo or run scope it can read; +- whether it is included in replay, export, or promotion evidence; +- how to inspect, clear, pin, and export it. + +The UI should treat this like an active context layer, not like invisible model +intuition. If a run cannot explain why a fact came from external memory, the +feature is not ready for default use. + +## Permissions And Privacy + +External memory must inherit the strictest relevant scope: + +- it must not cross repo/workspace boundaries without explicit approval; +- project-local config must not silently enable broad external-memory reads; +- replay must record external-memory inputs as evidence or mark replay as + unavailable/diverged; +- exports must make external-memory references visible without dumping private + raw state by default. + +## Deferred Work + +The following remain out of scope for the v0.9.0 cutline: + +- default-on Aleph-style memory for all WhaleFlow runs; +- automatic promotion from external memory into cached-main overlay; +- hidden retrieval behind ordinary prompts; +- hosted or shared external-memory services; +- treating external memory as a substitute for TraceStore replay. + +Future implementation should start with a read-only typed workflow node and a +mock replay fixture before adding any plugin-backed or live retrieval path.