| 1 | # Workflow External Memory Cutline |
| 2 | |
| 3 | **Status (2026-07-15): Principle-only cutline — current.** The boundary below |
| 4 | still holds at v0.9.0. Note the layer table names machinery (TraceStore, the |
| 5 | ARMH/RLM memo store, the cached-main overlay) that is proposed, not in the |
| 6 | tree; only user memory (`/memory`, `remember`) and RLM sessions exist today. |
| 7 | |
| 8 | This note resolves the next-major cutline for Aleph-style external memory in |
| 9 | Workflow. It is a design boundary, not a runtime implementation. |
| 10 | |
| 11 | ## Decision |
| 12 | |
| 13 | External memory should remain optional and explicit after v0.9.0. Normal Codewhale |
| 14 | operation must not depend on it, and Workflow must not silently enable it for |
| 15 | long-running runs. |
| 16 | |
| 17 | In a later release, external memory can appear only as: |
| 18 | |
| 19 | - an explicit workflow node whose inputs, outputs, scope, and permissions are |
| 20 | visible in the typed Workflow IR; |
| 21 | - an optional plugin or skill-backed tool that the user enables deliberately; |
| 22 | - a documented experiment whose state can be inspected, cleared, and exported. |
| 23 | |
| 24 | It should not be a hidden context substrate, a replacement for repo search, or a |
| 25 | default backing store for every workflow run. |
| 26 | |
| 27 | ## Layer Boundaries |
| 28 | |
| 29 | External memory is separate from the existing memory and replay layers: |
| 30 | |
| 31 | | Layer | Scope | Post-v0.9.0 rule | |
| 32 | | --- | --- | --- | |
| 33 | | User memory | Small durable user preferences and facts surfaced by `/memory` | Opt-in, user-owned, not workflow evidence | |
| 34 | | Repo search / codemap | Derived repo structure and search results | Rebuildable from the workspace; not a memory log | |
| 35 | | ARMH/RLM memo | In-session working memory and exact-context memoization | Visible hit/miss telemetry; not durable replay evidence | |
| 36 | | TraceStore | Recorded workflow, branch, leaf, and control results | Source of deterministic replay; no live model calls during replay | |
| 37 | | Cached-main overlay | Promoted lessons after review and replay | Inspectable and reversible; never mutates Git main | |
| 38 | | External memory | Large local or plugin-backed data outside normal context | Explicit node/plugin only; visible state and clear/export required | |
| 39 | |
| 40 | ## Visibility Requirements |
| 41 | |
| 42 | Any future external-memory implementation must show: |
| 43 | |
| 44 | - when it is active; |
| 45 | - which workflow node or plugin owns it; |
| 46 | - where its state is stored; |
| 47 | - what repo or run scope it can read; |
| 48 | - whether it is included in replay, export, or promotion evidence; |
| 49 | - how to inspect, clear, pin, and export it. |
| 50 | |
| 51 | The UI should treat this like an active context layer, not like invisible model |
| 52 | intuition. If a run cannot explain why a fact came from external memory, the |
| 53 | feature is not ready for default use. |
| 54 | |
| 55 | ## Permissions And Privacy |
| 56 | |
| 57 | External memory must inherit the strictest relevant scope: |
| 58 | |
| 59 | - it must not cross repo/workspace boundaries without explicit approval; |
| 60 | - project-local config must not silently enable broad external-memory reads; |
| 61 | - replay must record external-memory inputs as evidence or mark replay as |
| 62 | unavailable/diverged; |
| 63 | - exports must make external-memory references visible without dumping private |
| 64 | raw state by default. |
| 65 | |
| 66 | ## Deferred Work |
| 67 | |
| 68 | The following remain out of scope for the v0.9.0 cutline: |
| 69 | |
| 70 | - default-on Aleph-style memory for all Workflow runs; |
| 71 | - automatic promotion from external memory into cached-main overlay; |
| 72 | - hidden retrieval behind ordinary prompts; |
| 73 | - hosted or shared external-memory services; |
| 74 | - treating external memory as a substitute for TraceStore replay. |
| 75 | |
| 76 | Future implementation should start with a read-only typed workflow node and a |
| 77 | mock replay fixture before adding any plugin-backed or live retrieval path. |
| 78 |