Proposal: Memory Beads
Memory Beads
Document status. This document is a feature proposal. It defines the desired product behavior, capabilities, and architectural boundaries for Memory Beads. It is not an implementation plan.
Revision 3 — 2026-08-31. Applies the follow-up review round — archive collapsed into deletion-with-history, erasure separated from it, R27a, and the derivation-field refinements — with each change and its reason in the accompanying change-list comment.
Revision 2 — 2026-08-31. Applies the decisions recorded in the review thread; the change-list comment accompanying this revision enumerates every edit and its source.
Summary
Beads already has a small memory feature: bd remember stores a string under a key, bd recall reads it, bd memories lists or searches the key/value set, and bd forget removes a found non-empty entry. Out-of-band empty rows survive forget and require recovery. bd prime can inject memory bodies at session start. This is useful for a few reminders, but the storage model has no canonical Bead identity, no history reachable through the memory commands, no structured change authorship, no per-memory version identity, no explicit links, no way to remove a memory without losing its record, and no way for a task to cite the exact knowledge it used.
The gap shows up whenever project knowledge matters for more than one session. A corrected policy can silently replace the only copy of the old policy. A task cannot identify the exact historical state it was written against. Humans and agents cannot inspect how a decision changed or who changed it. At startup, loading every remembered body spends context before the agent knows what it needs.
The usual workaround is a collection of Markdown files, task descriptions, agent-specific memory files, and conventions about where to look. Those files can be good documents, but every tool assembles them differently. Knowledge gets duplicated, the task graph cannot cite it structurally, and a fresh agent has to rediscover the project's filing system before doing the work.
Task Beads already give project work an identity that outlasts any one agent session. Memory Beads expand the Beads core so durable project knowledge is a first-class Bead kind beside Task Beads. A Memory Bead has canonical identity, Markdown content, participation in shared Beads History with Change Attribution, deletion that keeps history, restoration, and explicit relationships to tasks and other memories. Retrieval starts with compact search or a task's references, followed by an explicit complete read. The existing memory commands keep working, with their canonical and compatibility meanings defined in R25.
The current memoryops.Memories contract and bd memory commands establish the existing keyed-memory behavior and public entry points. They are implementation evidence for the compatibility baseline, not definitions of the target's internal APIs or storage mechanisms.
Goals
Let the project remember
A new human or agent should be able to start from a task, find the knowledge that matters, read only what it chooses, and identify the exact historical Memory states it used. When knowledge changes, another person can inspect and compare retained history, see Change Attribution, make a deliberate correction under the common Versioned Bead rules, and retire the knowledge without losing its record.
The record stays useful outside an agent session. A human can read the same Markdown, review changes, follow links, and build a handbook or wiki view over the graph. Beads stores what its callers deliberately record. It does not manufacture durable memory from prompts, transcripts, tool activity, or a failed search.
Put work and knowledge in one core graph
Memory Beads extends Beads' core domain as a first-class Bead kind beside Task Beads. Memory identity, lifecycle, retrieval, and content semantics belong to the core Memory model. Versioning, historical addressing, writes, retries, concurrent editing, and conflicts come from shared Beads capabilities.
Bead References connect tasks to memories and memories to other memories without turning knowledge into workflow.
Core model
A Memory Bead is a first-class Bead containing durable Markdown knowledge. It exists or has been deleted — a deleted Memory has no current state while its retained versions stay addressable — and it never becomes ready, blocked, claimed, completed, or closed. Its durable state includes its title, body, optional key and aliases, outgoing references, metadata, derivation record, and Inception. It has no workflow-state dimension: versions of its durable state are its only change model.
Beads History is the shared, provider-neutral Beads capability for observing, comparing, attributing, and addressing change over time. Memory Beads requires this capability but does not define its identifiers, branches, retention, storage, concurrency, or conflict mechanics.
A Versioned Bead is a Bead whose durable state participates in Beads History. Memory Beads require that shared capability: a durable Memory change creates a version, while an unchanged Memory does not. An accepted version is immutable: its state never changes, a correction is a new version, and a removal leaves the version's address answering gone with the reason rather than resolving to anything else. Participation and behavior for other Bead kinds belong to their own contracts.
Change Attribution is shared Beads History metadata identifying who or what was responsible for an accepted version and the available change context. It is not editable Memory state and does not turn an otherwise unchanged request into a change. Inception is editable origin or transfer metadata within a Memory Bead, such as whether its current state was created natively, converted, or imported; changing it changes durable Memory state. Application-specific properties live in
metadata, never the body (R3).A Bead Reference is an explicit directional relationship;
relatedis the built-in baseline type and the vocabulary is open (R17). Every Bead Reference carries a version, implicitly or explicitly: a specific version ID, or the well-known ID meaning latest — the default when none is stated. A reference whose version is a specific version ID is pinned — a Historical Bead Reference — and identifies one exact retained state of one Versioned Bead under the addressing model Beads History defines; that meaning does not imply the provider can reconstruct an entire historical project snapshot. The uses defined here have at least one Memory endpoint. A Bead Reference is informational, carries no instructions or authority, and never affects readiness.A context consumer is an application such as MindSpec that selects Beads and other project artifacts, assembles task context, and records what it used. It consumes Memory Beads but owns its artifact types, budgets, ordering, hashes, and receipts.
User scenarios
Remembering and maintaining knowledge
S1. Record durable knowledge without inventing a name
A developer records why the project avoids a tempting dependency. They supply a Markdown body but no title or key. Beads derives a short title, creates a Memory Bead with a canonical ID and first attributed version, and does not invent a key. A human may add or rename a familiar key later; former keys remain aliases, while agents can continue using the canonical ID.
S2. Search before writing and improve the existing memory
An agent is asked to preserve a newly discovered release convention. It searches compact memory results and finds an existing convention that already covers the subject. It recalls the complete body and updates that same Memory Bead using the common write rules for Versioned Beads rather than leaving a duplicate. An external quality tool may flag a possible duplicate or stale statement, but Beads does not decide that itself.
S3. Retire knowledge without losing the record
A workaround is no longer current. A maintainer forgets its Memory Bead. It disappears from current state and from search, but its retained versions and their Change Attribution remain readable by version according to the project's retention policy, pinned references to it still resolve, and a reference following latest reports that the target was deleted. If the workaround becomes relevant again, restoring it revives the same identity from a retained version rather than creating a replacement.
Recalling and assembling context
S4. A fresh agent recalls only what it needs
A fresh supported coding agent starts from generated Beads guidance. It searches compact summaries, selects two plausible memories, recalls their complete bodies, and reports the Bead IDs and Historical Bead References that informed its work. bd prime, task loading, and search results do not inject unrelated memory bodies.
S5. A task cites the policy it depends on
A task has a Bead Reference to a security policy. Its structured record exposes the target identity and optional Historical Bead Reference without loading the target body. The task body explains why the policy matters. The executing agent explicitly recalls it before acting, and an exact historical reference continues to identify the same retained policy state after the policy changes.
S6. MindSpec builds a deterministic context pack
A MindSpec-like context consumer reads a task's structured record, follows selected Bead References, and recalls exact historical Memory states. It combines those records with its own specs, ADRs, domain documents, and source files under a deterministic token policy. The resulting receipt identifies or hashes every input and explains why each was included. Beads makes each selected Memory's canonical identity, exact content, and Change Attribution available together; MindSpec decides which of those facts to record and owns the taxonomy, ordering, token tiers, file handling, and receipt format. Its pinned context-pack budgeter specification documents its consumer-owned ordering, budgeting, input hashing, and receipt behavior.
Versioning and integrity
S7. Two writers do not silently overwrite each other
Two people edit the same Memory Bead. Their writes follow the common Versioned Bead rules, so one cannot silently overwrite the other. After resolving the concurrent change through those shared rules, retained history and comparison show what changed and its Change Attribution.
Linking knowledge to work
S8. A task and a memory link without changing workflow
A task links to the project's release policy, and that Memory Bead links to a supporting design rationale. Both links are explicit, directional, and non-blocking. The task keeps its existing dependency and readiness behavior, the source body explains why the reference matters, and neither task display nor reference traversal loads the target body. A caller can later remove either relationship with bd unlink <source> <target>; removing an outgoing Memory reference versions that source Memory without changing the target.
S9. A referenced target changes state
A task refers to the current release policy, and a Memory Bead refers to a supporting task. The policy or the supporting task is later deleted. Each surviving source keeps the stored reference without being revised merely because the target changed. Inspection reports the target's observed state without changing task readiness or silently retargeting the link.
S10. An exact historical reference does not drift
A reference whose version is latest follows the Memory Bead's current state. A pinned reference continues to identify the same retained state after the target changes: it resolves to exactly that state or to a typed refusal, never to a different one — a pinned reference can be superseded by newer versions of its target, but what it names never changes. Outgoing views for an exact historical state remain bound to that state, and a bounded incoming-reference view reports whether it is complete.
Compatibility and interchange
S11. Existing key/value memory converts without silent loss
Converting legacy key/value memory to canonical Memory Beads preserves keys, bodies, and any history or Inception that can be represented truthfully. A legacy key with an empty value becomes a Memory with that key, a title derived from it, and an empty body. The accepted conversion change receives ordinary Change Attribution, while missing legacy authorship is disclosed rather than invented. Ambiguity, collisions, corruption, or another credible loss risk produces an actionable failure rather than false success, partial visibility, or invented evidence. If conversion is interrupted, callers see the still-usable legacy view, the complete canonical view, or an inspectable unavailable state that can be retried or recovered; they never receive an unexplained mixed view.
S12. Familiar commands map onto canonical Memory Beads
Existing users keep bd remember, bd memories, bd recall, and bd forget, but their target meanings are unambiguous. remember writes, canonical memories need no key, forget deletes without erasing history, structured discovery uses Bead IDs and compact records, and prime teaches selective retrieval instead of injecting bodies. Existing bd memories --json callers continue to receive the human-key-to-complete-body map, while keyed Go and HTTP interfaces remain compatibility projections of the same canonical Memory Beads. Canonical ID-based discovery is a separate structured representation that also supports unkeyed memories. bd remember release-policy writes a Memory whose body is release-policy; reading a Memory uses bd recall.
S13. Memory participates safely in shared interchange
A team transfers a selected graph containing tasks, memories, and their references through the shared Beads interchange facility. The destination either preserves the selected Memory state and reference meaning or rejects the transfer without a partial connected graph. A Memory is never identified or retargeted merely because a human key or similar-looking ID matches.
Ecosystem use
S14. A viewer and a quality tool use the same public records
A viewer renders memory summaries, complete current and retained historical state, existence or deletion, references, comparisons, and Change Attribution without reading provider tables. A separate quality tool examines the same structured data for possible staleness, contradiction, duplication, or weak evidence. Beads preserves the material and exposes shared history capabilities; the tool makes the judgment.
Change over time
S15. Temporary knowledge carries its own validity
A developer records a workaround that is only valid until a dependency ships its fix, and records that validity window in the Memory's metadata at write time. Beads moves nothing on a clock: consumers that care filter on the window, and when the fix ships the developer forgets the Memory. If the fix slips, the developer changes the window with an ordinary attributed edit; if the workaround is needed again after being forgotten, restoring it revives the same identity from its retained history.
S16. An application uses Beads History to update its own representation of memories
An application queries ordinary Beads History for all Bead changes from the position it last processed — or from a chosen instant on a first read — selects the Memory Bead changes, including removals of retained versions with their reasons, and reads the affected Memories through their public structured interfaces. The application decides how to synchronize those changes into Obsidian or any other application-specific representation. Beads does not own that synchronization process.
Requirements
Memory model and authoring
R1. Memory is a first-class core Bead kind. This feature intentionally expands the Beads charter from project work alone to peer core concepts for project work and durable project knowledge. A Memory Bead uses type: "memory", participates in the Bead graph, and exists beside Task Beads rather than beneath the task model. Readiness, assignment, priority, claiming, completion, closure, and workflow dependencies do not apply to it. Queries and mutations whose meaning requires Task workflow state do not select or affect a Memory, and a workflow mutation addressed to one fails with a typed error. Generic Bead operations such as listing by kind, showing identity, and graph traversal can include Memory Beads. (S1, S3)
R2. Canonical identity does not depend on a human key. Every Memory Bead has a canonical Bead ID, owning Project ID, and supplied or derived title. A Memory Key is optional metadata and a selector. An application may encode prefixes, paths, or other structure in a key, but Beads treats the complete value as one opaque selector and assigns no meaning to its segments. Renaming one retains the former key as a visible alias. Current keys and aliases share one project-wide uniqueness namespace; deleting a Memory releases them, and an ordinary attributed rename or key removal frees a name from a live one. Canonical Bead ID wins positional ambiguity, while explicit selectors choose ID or key lookup. Unkeyed memories remain fully usable, and canonical machine-readable records never substitute a key for identity. The keyed JSON compatibility projection in R25 does not redefine canonical identity. (S1, S2)
R3. Core fields describe portable Memory semantics; metadata is the extension point. A core field holds only what is portable before an author knows how a memory will be used; a categorical field whose value would change with intended use is not core. Application-specific properties — ADR status, evidence, validity, confidence, context tier, a must-be-present marker, a class taxonomy — belong in the Bead's structured metadata, the extension point every Bead already carries. Metadata is part of durable Memory state: changing a key mints a version, it travels with the version, and — because versions are retained under policy — a value that must not persist does not belong in it. The Markdown body is content and carries no Bead properties. It may contain anything, including frontmatter and ordinary Markdown links to files, documents, websites, or other non-Bead resources; Beads preserves body content verbatim but does not interpret it, and never treats body text as Bead References or validates, synchronizes, authorizes, retargets, or promises the continued existence of link targets. Core Beads does not acquire each application's taxonomy.
Two core fields record a Memory's own derivation, because a record that dropped its evidence must not read like one that never had any. Derived-from is a core field, not a graph edge: a list of reference-shaped values — canonical ID and optional version — with three observable states: absent (a pre-schema or converted record; derivation unknown), an empty list (the author asserts the content directly — a deliberate value), or one or more entries (the tasks, documents, Memories, or external sources it was written from). Derivation completeness is a tri-state — complete, incomplete, or unknown — unknown for converted records and never defaulted. A Bead source is checkable by ordinary read; a non-Bead source is carried with
Source: gastownhall/beads