Code beads and persistent memory

Externalize project memory

Adaptive-system development spans experiments, failures, approvals, and handoffs. Conversation context is not an authoritative project record. Code beading is used here as a descriptive term for small, persistent, linked work units with explicit state and acceptance criteria.

Bead structure

bead <- {
    id: "MB-1842",
    title: "Calibrate low-confidence abstention for classifier v7",
    type: "experiment",
    status: "ready",
    priority: 2,
    discovered_from: "MB-1790",
    blocks: ["MB-1848"],
    inputs: ["artifact-sha256", "dataset-manifest-sha256"],
    acceptance_criteria: [
        "ECE <= 0.04 on validation suite",
        "abstention recall >= 0.95 on critical slice",
        "p95 latency increase <= 5 ms"
    ],
    evidence_required: ["evaluation-card", "review-record"],
    owner_role: "evaluation-engineer",
    updated_at_utc: NOW_UTC()
}

Why structure beats flat notes

A task graph can answer what is ready, what is blocked, which experiment produced a finding, and which acceptance criteria remain unmet. Flat Markdown plans often mix obsolete ideas, current decisions, and completion claims without machine-readable state.

Relationship to lineage

Beads describe work and decisions. Lineage describes artifacts and transformations. Link them both ways: a candidate records the bead that authorized its creation, and the bead records the resulting artifact and evidence identifiers.

Session handoff

At the start of a session, an agent receives only the highest-priority unblocked beads plus relevant architecture decisions and artifact manifests. At the end, it writes evidence, creates discovered work, and updates status through a constrained interface.

PROCEDURE agent_session(agent_role)
    work <- QUERY_READY_BEADS(agent_role, limit = 3)

    FOR each bead IN work
        context <- LOAD_REFERENCED_EVIDENCE(bead)
        result <- EXECUTE_WITHIN_ROLE(bead, context)
        APPEND_RESULT_EVIDENCE(bead.id, result)

        IF result.discovered_work EXISTS
            CREATE_CHILD_BEADS(bead.id, result.discovered_work)
        END IF

        UPDATE_STATUS_FROM_ACCEPTANCE_CRITERIA(bead.id)
    END FOR
END PROCEDURE

Governance controls

Agents may create and update beads within role-based limits, but cannot delete audit history, rewrite completed acceptance criteria, or mark high-risk work approved. Human or policy roles own sensitive transitions.

File-backed implementation

A small system can store each bead as canonical JSON or append-only JSONL plus generated indexes. Use atomic writes and stable identifiers. A database becomes useful for large dependency graphs, but the information model should remain portable.