docs/rfcs/WORKFLOW_EXTERNAL_MEMORY.md

Rama main · réplica de lectura del repositorio original.

# Workflow External Memory Cutline

**Status (2026-07-15): Principle-only cutline — current.** The boundary below
still holds at v0.9.0. Note the layer table names machinery (TraceStore, the
ARMH/RLM memo store, the cached-main overlay) that is proposed, not in the
tree; only user memory (`/memory`, `remember`) and RLM sessions exist today.

This note resolves the next-major cutline for Aleph-style external memory in
Workflow. It is a design boundary, not a runtime implementation.

## Decision

External memory should remain optional and explicit after v0.9.0. Normal Codewhale
operation must not depend on it, and Workflow must not silently enable it for
long-running runs.

In a later release, external memory can appear only as:

- an explicit workflow node whose inputs, outputs, scope, and permissions are
  visible in the typed Workflow 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 | Post-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 Workflow 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.