Research: principles for docs vs memory separation (2026-04-18)

Migrated from Plane work item DASHE-12 on 2026-04-18. The original Plane content was a stub pointing to a Plane Page; that Page was discarded when the Plane workspace retired. The content below reconstructs the intended research from the sibling docs and the Karpathy LLM Wiki analysis.

Context

The rig has three candidate homes for knowledge:

Docs — markdown in dashecorp/rig-docs, PR-reviewed, durable
Memory MCP — Postgres + pgvector, auto-retrieved by agents, mutable, ephemeral
Agent character prompts — HelmReleases in dashecorp/rig-gitops, baked into deployment

Without a rule, these overlap. Five candidate principles to pick an ownership rule:

1. Immutability

Docs are durable and reviewed. Memory is ephemeral and overwritable.

Rule: if you write it for future-you (or the next human) to read, it’s a doc. If you write it so the next agent run uses it, it’s memory.

2. Review gate

Docs go through PR review (Review-E + human). Memory writes are un-gated — the agent decides inline whether something is worth remembering.

Rule: the review gate prevents hallucinated facts from becoming canon. But review costs time. Memory trades the gate for speed.

3. Retrieval pattern

Docs are grep’d or read as canonical pages. Memory is queried by similarity (semantic) for relevant operational bits mid-task.

Rule: if an agent needs to recall something during work, that’s memory. If an agent needs to reference a fixed standard, that’s docs.

4. Audience

Docs are for humans and agents. Memory is primarily for agents (humans read it only through a surfacing pipeline).

Rule: humans can’t — shouldn’t — read raw memory blobs. They read docs. Memory is machine-to-machine operational state.

5. Failure tolerance

Memory loss is degraded-but-recoverable. Learnings re-accumulate over runs. Docs loss breaks the rig until restored.

Rule: treat docs as ground truth requiring backup and version control (git gives this). Treat memory as an eventually-consistent cache that can be wiped.

Synthesis

All five principles point in the same direction: docs are the canonical, human-reviewed, durable layer; memory is the ephemeral, agent-operational, vector-queryable layer. The Karpathy LLM Wiki pattern encodes the same split as wiki/ (durable, LLM-maintained) versus a separate operational cache.

The rule operationalised:

Docs own — architecture, conventions, user stories, research, proposals, decisions, runbooks, glossary
Memory owns — per-run context, prior reviewer decisions, encountered pitfalls awaiting promotion, session-local state
Agent character prompts own — role definition, lore, tool list (small, versioned in rig-gitops HelmReleases)

Promotion rule (memory → docs): any memory with importance ≥ 4 and hit_count ≥ 5 is a candidate for promotion to a docs entry by a weekly Lint pass. See sibling anti-drift lint rules.