AIP-72: MEMORY (memory/v1): typed memory items about a principal and its work

Fixes the stored memory document, one markdown file per memory item: a small typed assertion (user, feedback, project, reference) about a principal or its work, with AIP-10 base fields, a lifecycle (active, then superseded or archived), a lifetime, provenance and capture blocks, and a free markdown body; then the memory store a host reads and writes items through (propose or commit, read, list, search, supersede, archive, compare-and-set, no hard delete) and the projection of items into each harness session (a bounded digest injected natively or through the system prompt, native-memory changes captured back as proposals); then the node and operator anchors, which scope an item's visibility by AIP-34 node and mark its ownership by AIP-9 operator, and the rule that every store operation applies the session's node projection.

FieldValue
AIP72
TitleMEMORY (memory/v1): typed memory items about a principal and its work
StatusDraft
TypeSchema
Doctypememory/v1 (one memory item, written as a markdown file with YAML frontmatter)
RequiresAIP-1, AIP-2, AIP-10 (base fields, knowledge providers), AIP-45 (the projection declaration)
Composes withAIP-9 (operator memory ownership), AIP-11 (lessons), AIP-34 (node scope of a session, walls), AIP-42 (memory block of an agent), AIP-68 (the secretary clerk promotes proposals into a store), AIP-71 (native first projection)
Created2026-10-28
Resources./resources/aip-72: MEMORY.schema.json

Abstract

A memory item is a small typed assertion about a principal or its work: who the user is, how they want the agent to behave, what is going on in a project, where to find something. memory/v1 fixes how one item is stored: a markdown file whose YAML frontmatter carries the AIP-10 base fields, a closed type (user | feedback | project | reference), a lifecycle (active, then superseded or archived), a lifetime, and provenance and capture blocks; the markdown body is free. It then specifies the store a host reads and writes items through, and the projection that shows in-force items to a harness session at spawn and captures the session's native-memory changes back as proposals. Where the host declares an AIP-34 tree, an item also carries a node anchor (where it is visible) and, when an AIP-9 operator wrote it, an operator anchor (whose it is), and the store applies the session's node projection to every operation (section 10).

Motivation

Agents already keep this kind of memory, each in its own shape: a harness's native auto-memory directory, a system-prompt file, a clerk's facts store. None of them can be read by another runtime, and none records where a claim came from or whether it still holds. A writer and a reader that agree on one document can exchange items without a translation per pair, and a reader can tell a live item from a retired one.

Memory is not knowledge, and not a lesson:

  • AIP-10 knowledge entries are curated wiki pages compiled from immutable raw sources and pulled by query. A memory item is mutable, scoped to a principal, and carries its own lifecycle; it is pushed into context at spawn and searched on demand. A memory item reuses the AIP-10 base fields so the same tooling can list both, but it is a separate doctype.
  • AIP-11 lessons are transferable heuristics distilled from completed runs, with trigger conditions and success counts. A memory item is a single assertion (a preference, a fact about a project, a pointer), not a playbook entry; it has no trigger and no outcome count.

Memory is also scoped. A host that serves several nodes of an AIP-34 tree, or several trees, holds items that must not reach every session: a company's decisions are not a personal tree's facts, and one guild's notes are not its sibling's. A flat tag match cannot say that, and global crosses everything. Section 10 adds the node anchor and the projection that give memory the same walls as files.

Specification

The keywords MUST / SHOULD / MAY are RFC 2119.

1. Document

A memory item is one UTF-8 markdown file: a YAML frontmatter block fenced by --- lines, then a markdown body. The frontmatter is validated by MEMORY.schema.json, in which the body property stands for the markdown after the closing fence. The registry file name is MEMORY.md; a store MAY name item files otherwise (the reference store writes items/<type>/<id>.md).

---
schema: memory/v1
slug: "cite-sources"
kind: feedback
title: "Cite sources"
updated_at: "2026-10-13T11:30:00.000Z"
id: mem_test001
name: "cite-sources"
type: feedback
polarity: do
description: "Always cite sources"
tags: ["global", "agent:assistant"]
lifetime: { kind: "durable" }
status: active
created: "2026-10-13T11:30:00.000Z"
written: "2026-10-13T11:30:00.000Z"
decidedBy:
  rule: "classifier-confident"
  source: "builtin"
provenance:
  source: "converse"
  quote: "always cite your sources"
  at: "2026-10-13T11:00:00.000Z"
  extractorVersion: "extractor@3"
capture:
  mode: "batch"
  producer: "clerk:user"
  capturedAt: "2026-10-13T11:00:00.000Z"
---

Always cite sources.

2. Fields

FieldTypeRequiredMeaning
schema"memory/v1"canonicalDoctype discriminator.
slugstring, ^[a-z][a-z0-9-]*[a-z0-9]$, 2 to 96 charscanonicalStable kebab-case identifier (AIP-10).
kindstring, ^[a-z][a-z0-9-]*$canonicalAIP-10 spelling of the item type; one of user, feedback, project, reference for a memory/v1 item.
titlestring, 1 to 200 charscanonicalHuman-readable title (AIP-10).
updated_atISO 8601 date-timecanonicalLast content write (rule 6).
idstringlegacyStore identifier (e.g. mem_qc8f407g).
namestring, up to 1000 charslegacySlugified name, kept apart from slug for round-trip.
typeuser | feedback | project | referencelegacyThe closed memory type.
descriptionstring, up to 4000 charsnoOne-line summary, independent of the body.
tagsstring[]noFree labels; scope anchors in formatted form (global, project:<slug>, agent:<slug>, pr:<owner>/<repo>#<n>, and, section 10, node:<id> and operator:<id>).
polaritydo | dontnoFeedback polarity; only on feedback items.
lifetimeobjectnoHow long the item holds (section 4).
statusactive | superseded | archivednoLifecycle (section 3); absent means active.
createdISO 8601 date-timenoCreation time.
writtenISO 8601 date-timenoLegacy mirror of updated_at.
decidedBy{ rule, source }noThe rule that decided the item, and where that rule came from.
provenanceobjectnoWhere the claim was observed (section 5).
captureobjectnoWho and how captured it (section 5).
evidenceobjectnoTrust and impact accounting at write time (sourceKind, trust, explicitness, corroborations, contradictsActive, impact, lifetime, anchorsResolved, ageHours, flags).

"canonical" fields are REQUIRED on a canonical memory/v1 item. An item without them is valid only if it carries the legacy trio id, name, type (items written before this doctype existed). No other top-level key is allowed.

3. Lifecycle

active ──> superseded
   └─────> archived

A writer creates an item active. superseded means a newer item replaces it (for example, a duplicate folded into another). archived means it is retired with no replacement (its lifetime ran out, or its anchor no longer resolves). Both are terminal. An item is retired by rewriting its status, not by deleting the file.

4. Lifetime

kindExtra fieldHolds
durablenoneuntil retired
untilat (date-time), REQUIREDuntil at
whileanchor, REQUIREDas long as the anchor holds (a task open, a PR open...)
sessionnonefor the session that produced it

An anchor is { kind: "global" }, { kind: "project" \| "contact" \| "agent", slug }, { kind: "task" \| "session" \| "node" \| "operator", id } or { kind: "pr", repo, number }. A node anchor holds while the node still resolves in its tree, and an operator anchor while the operator still resolves (section 10).

5. Provenance and capture

provenance records where the claim was observed: source (a source class such as converse or transcript), sessionId, ref (an opaque pointer into the source, such as a message uuid or a file path), quote (the verbatim text backing the claim), at (when it was observed) and extractorVersion (which extractor generation produced it).

capture records who and how captured the item, apart from where the claim came from: mode (live during the session it describes, or batch by a later pass), producer (the capturing component) and capturedAt.

6. Body

The markdown body is free. It holds the assertion itself in prose; a writer MAY render a feedback item as the rule, then a "why" and a "how to apply" paragraph, but readers MUST NOT depend on any body structure.

7. Conformance

Writer rules:

  1. A writer MUST emit frontmatter that validates against MEMORY.schema.json, and MUST set the canonical fields (schema, slug, kind, title, updated_at) on every item it creates.
  2. When both kind and type are present they MUST be equal.
  3. Every string-typed field MUST be written so a YAML 1.2 parser reads a string: a value such as true, null, no or 2026 MUST be quoted.
  4. An optional field with no value MUST be omitted, never written empty (in particular provenance.sessionId and provenance.ref).
  5. polarity MUST NOT be set on an item whose type is not feedback.
  6. A writer MUST set updated_at when it creates the item and when it changes any field other than status. A status-only rewrite MAY leave updated_at unchanged, and MUST leave every other byte of the file unchanged.
  7. A writer MUST only move status from active (or absent) to superseded or archived, and MUST NOT move it out of either.
  8. A writer SHOULD record provenance.source, provenance.at and, when the claim comes from a quotable source, provenance.quote verbatim.

Reader rules:

  1. A reader MUST accept both canonical and legacy items (section 2), and MUST treat an absent status as active.
  2. A reader MUST NOT present a superseded or archived item as being in force; it MAY show it as history.
  3. A reader SHOULD treat an active item whose lifetime no longer holds (an until past its at, a while whose anchor is gone, a session item outside its session) as not in force, even before a writer archives it.
  4. A reader MUST NOT reject an item because of its body.

8. Store

A memory store holds memory items and offers six operations. It keys items by id: a commit of an item without one gets an id assigned by the store. slug, when present, is a second handle (rule 14). The files are the source of truth; any index a store keeps (full text, embeddings, a knowledge provider) is derived from them and MUST be rebuildable from the files alone.

  • write an item, in one of two modes. propose records a proposal: a memory/v1 document that is not an item yet, is not in force, and is never projected into a session. commit creates the item, or replaces the content of an existing one.
  • read one item by id. A lookup by slug is a list with the slug filter, and finds at most one active item.
  • list items, filtered by type, status, tag (scope anchors in formatted form) and whether the item is in force (rules 10 and 11). With proposals: true it lists the pending proposals instead.
  • search items by a free query. A store MAY delegate the query to an AIP-10 knowledge provider that indexes the items; every hit MUST say whether it is a memory item of this store (source: "memory", with its id) or something else the provider returned (source: "knowledge").
  • supersede an item by a new one: the new item is committed, then the old item's status becomes superseded. The old item stays readable.
  • archive an item: its status becomes archived. The item stays readable.

A proposal that will not be committed is dropped with dismiss. A proposal is not an item, so dropping it erases nothing that was in force.

Scope. Where the host declares an AIP-34 tree, every operation on behalf of a session carries that session's scope (section 10) and applies its node projection: list, search and read return only items in the projection, propose and commit stamp and check the node anchor, and supersede, archive and dismiss act only on items and proposals in it. This holds for proposals as much as for items. A call without a scope is a host call, not a session call (section 10, rule 30).

type MemoryType = "user" | "feedback" | "project" | "reference"
type MemoryStatus = "active" | "superseded" | "archived"

// MemoryDocument: the frontmatter fields of section 2 plus `body`.
interface MemoryRecord {
  item:        MemoryDocument
  revision:    string             // opaque; changes on every byte change
  proposalId?: string             // set on a proposal, absent on an item
}

// Section 10. Built by the host from the calling session, never by the store.
interface MemoryScope {
  nodes:     readonly string[]    // node projection: AIP-34 ids, nearest first, already
                                  // cut at a sealed or hard node; empty = the session
                                  // has no node scope
  tree?:     string               // id of the root node of the session's tree
  operator?: string               // operator anchor id, when the session runs an operator
}

interface MemoryFilter {
  type?:      MemoryType | readonly MemoryType[]
  status?:    MemoryStatus | readonly MemoryStatus[]
  slug?:      string              // matches at most one active item
  tags?:      readonly string[]   // match any, e.g. ["global", "project:acme"]
  inForce?:   boolean             // rules 10 and 11, at the store's clock
  proposals?: boolean             // list proposals instead of items
  scope?:     MemoryScope         // section 10; absent = a host call
}

interface MemorySearchHit {
  source:   "memory" | "knowledge"
  id?:      string                // REQUIRED when source is "memory"
  slug?:    string
  title:    string
  snippet?: string
  score?:   number
  ref?:     string                // provider pointer when source is "knowledge"
}

interface MemoryStore {
  write(
    item: MemoryDocument,
    opts: {
      mode: "propose" | "commit"; ifRevision?: string; fromProposal?: string
      scope?: MemoryScope
      owner?: "operator" | "node"   // section 10, rule 32; default "operator"
    },
  ): Promise<MemoryRecord>
  read(id: string, opts?: { scope?: MemoryScope }): Promise<MemoryRecord | null>
  list(filter?: MemoryFilter): Promise<readonly MemoryRecord[]>
  search(
    query: string,
    opts?: { filter?: MemoryFilter; limit?: number },
  ): Promise<readonly MemorySearchHit[]>
  supersede(
    oldId: string,
    next: MemoryDocument,
    opts?: { ifRevision?: string; scope?: MemoryScope },
  ): Promise<{ old: MemoryRecord; next: MemoryRecord }>
  archive(id: string, opts?: { ifRevision?: string; scope?: MemoryScope }): Promise<MemoryRecord>
  dismiss(proposalId: string, opts?: { scope?: MemoryScope }): Promise<void>
}

search and list default to inForce: true when no status or inForce filter is given. A failed operation rejects with a conflict (rule 17), a validation error naming the field, or a not-found error. An item or proposal outside the scope of the call is reported as not-found, never as a distinct error (rule 28).

Reference layout

The reference store is a directory. Every implementation SHOULD be able to read it, whatever it uses internally, so a store can be exported to it and imported from it:

<store root>/
  items/<type>/<id>.md           # one memory/v1 item per file; path stem = id
  proposals/<proposal-id>.md     # pending proposals, not items

The reference store computes revision as the SHA-256 of the file bytes, and a proposal id as the SHA-256 of the rendered proposal, so the same proposal written twice lands on the same file.

Store rules:

  1. A store MUST validate every committed item against the writer rules (1 to 8) and MUST reject an item that breaks one, naming the field.
  2. An id MUST identify at most one item in a store, across all types; a commit that changes an item's type moves the item and never leaves two files for one id. A slug, when present, MUST be unique among the active items of the store, and a store MUST reject a commit that would give two active items the same slug.
  3. A store MUST only change status from active to superseded (through supersede) or to archived (through archive), and MUST reject a commit that would move an item out of superseded or archived (rule 7). An item replaced in substance is superseded under a new id, not rewritten in place.
  4. A store MUST NOT hard delete an item. The only exception is erasure at the principal's request (Security Considerations), which is not part of this interface.
  5. Writes use compare-and-set. A commit that would change an existing item, a supersede and an archive MUST carry the ifRevision the caller last read, and the store MUST reject the operation with a conflict when the current revision differs. Last writer wins was rejected because a clerk pass and a human edit can target the same item, and a silent overwrite would lose a retirement or a correction with no trace.
  6. A write is idempotent by id: a commit whose item equals the stored one in every field but updated_at and written, body included, succeeds without touching the file and returns the current revision, with or without ifRevision. A propose of a document already pending returns the existing proposal.
  7. On a commit that creates an item or changes any field other than status, the store MUST set updated_at (and written, when the item carries it) to the commit time. Supersede and archive are status-only rewrites: they MUST leave updated_at and every other byte of the file unchanged (rule 6).
  8. Supersede MUST commit the new item before it retires the old one, so an interrupted supersede leaves both items active, never neither. The new item MUST have a different id from the old one. It MAY carry the old item's slug: the check of rule 14 then ignores the item being superseded, and until an interrupted supersede is retried a lookup by that slug returns the item with the later updated_at.
  9. A store MUST NOT turn a proposal into an item on its own. A proposal becomes an item only through a commit by a writer the host's write policy allows; a commit with fromProposal drops that proposal once the item is written.
  10. A search hit with source: "memory" MUST name an item of this store that is in force at the time of the call, unless the filter asked for other statuses. A store that delegates search MUST check each hit against the files (the index may be stale) and drop or relabel a hit that no longer matches.

This revision records no link from a superseded item to the item that replaced it; a store MAY keep that link in its own index, and the result of supersede returns both.

9. Projection

A projection is how a session sees memory. It has two halves.

  • Inject, at spawn: the host computes a digest of the in-force items scoped to the session and hands it to the session, either in the system prompt or by writing it into the harness's native memory location.
  • Capture, during or after the session: changes the session made to its native memory are read back and written to the store as proposals. A capture never commits.

Each AIP-45 harness declares what it supports in capabilities.memory:

interface MemoryProjectionCapability {
  inject:  "native-dir" | "system-prompt" | "none"
  capture: "native-dir-diff" | "none"
}
  • inject: native-dir means the harness reads a native memory directory or file at start, and the harness can write items into it.
  • inject: system-prompt means the harness has no native memory but accepts appended system-prompt text at spawn.
  • inject: none means neither.
  • capture: native-dir-diff means the harness writes its native memory location during the session, and the harness can diff it against what was projected.

An absent declaration reads as { inject: "none", capture: "none" }. Like a capability in AIP-71, the declaration is metadata: it does not enable a projection by itself.

Resolution

Native first, system prompt as the fallback, one owner per session, as in AIP-71 section 4:

  1. When the harness declares inject: native-dir and the host implements the native projection for that harness, the digest is written into the native location.
  2. Otherwise, when the harness declares native-dir or system-prompt and the host can append to that session's system prompt, the digest is appended to the system prompt.
  3. Otherwise the session gets no digest at spawn.

A host MUST use exactly one inject path per session: the same items MUST NOT reach a session through both. A host MUST NOT claim the native path for a harness whose native projection it does not implement, even where the harness declares it. Capability read surfaces SHOULD report the effective inject and capture paths.

Digest

The digest is the in-force items (rules 10 and 11) whose tags include global or one of the session's anchors (its project, agent, task, PR, session or operator, as the host resolves them). An item with no anchor tag is treated as global; a node: or operator: tag is not counted as an anchor here (section 10). Where the session has a node scope, the digest is further limited to the items in the session's node projection (section 10), which it applies as one more condition on the same selection, so an item the projection excludes never reaches the digest whatever its other anchors say. For each item it carries:

  • type, id, slug when present, and title;
  • polarity, on a feedback item;
  • description when present, otherwise the first paragraph of the body.

Items are ordered by type (feedback, user, project, reference), then from the most specific anchor to global (session, task, PR, operator, agent, project, node from the session's own node outward, global), then by updated_at, newest first. The host chooses a size bound for the digest and SHOULD keep it near a few thousand characters. The host MUST cut whole items, never part of one, and MUST end a cut digest with the number of in-force items left out and the way to reach them (a search tool, when the host offers one).

On the system-prompt path the digest is one delimited block that presents the items as recorded data, not as instructions. On the native-dir path the harness writes the digest or one file per item in the harness's native format; the id MUST survive in a recoverable form (for example the file name stem), so a capture can map a changed file back to its item.

A session that gets no digest (step 3) still reaches memory if the host exposes the store's read, list and search operations as tools. A host SHOULD expose them to every session whose agent has memory enabled (AIP-42 memory.enabled).

Capture

With capture: native-dir-diff, the host records the native location as it projected it, then diffs it at session end and MAY diff it earlier (AIP-37 compact-start or turn-end). Each difference becomes a proposal, never a commit:

DifferenceProposal
a new entrya new item
a changed projected itemthe same id with the new content
a removed projected itemthe same id with status: archived

Accepting a proposal that carries status: archived is an archive of that item (rule 15), not a commit.

A captured proposal carries capture.mode: live, a capture.producer naming the projection, provenance.source: native-memory and the session id in provenance.sessionId. Where the session has a node scope it also carries the session's node anchor and, when the session runs an operator, its operator anchor, by the write defaults of section 10 (rule 31). Proposals are promoted into items by a writer the host's write policy allows, such as the AIP-68 secretary clerk (rule 21).

With capture: none nothing is read back from the harness; memory written during the session reaches the store only through tools or a later clerk pass over the transcript.

Projection rules:

  1. A host MUST NOT project a proposal, or an item that is not in force.
  2. A host MUST NOT commit a captured change; it MUST write it as a proposal.
  3. A host MUST NOT inject the same items through more than one path in one session.
  4. A host that cuts the digest MUST cut whole items and say how many it left out.

10. Node scope

Sections 8 and 9 scope memory by flat anchors. This section adds the two anchors that tie memory to an AIP-34 tree and to an AIP-9 operator, and the projection every store operation applies. It matters where the host declares a tree. A host with no declared node keeps the behaviour of sections 8 and 9: a session there has no node scope (AIP-34, "Node scope of a session") and the walls do not apply to it.

Two anchors, two meanings

  • Node anchor, { kind: "node", id }, formatted node:<id>. id is the AIP-34 id of a node (@<owner>/<slug>). It scopes visibility: the item belongs to that node, and is visible to the sessions whose node projection (next subsection) includes it.
  • Operator anchor, { kind: "operator", id }, formatted operator:<id>. id is the operator body of an AIP-54 operator: ref (<slug>, or <slug>@<workspace> for an operator of another workspace), the anchor AIP-9 puts on the memory of the operator it resolves. It marks ownership: whose memory the item is. It never makes an item visible anywhere by itself.

An item carries at most one node anchor and at most one operator anchor. A reader that finds several node anchors treats the item as visible only where all of them are in the projection.

Node projection

The node projection of a session is the list of nodes whose items it can be shown. Walk up from the session's node scope, which is read from the calling session's ground as AIP-34 defines it (at spawn for the digest, on every call for the tools). The projection holds the session's node and each ancestor inside the same tree, up to the tree root, and stops after the first node whose wall is sealed or hard: that node is in, nothing above it is. It never holds a sibling, a descendant, a node of another tree, or a node reached only through a door (includes/exports). A session with no node scope has an empty projection.

The host computes the projection, nearest node first, and gives it to the store as the nodes of a MemoryScope. A store does not compute it and does not read it from its own configuration. The projection never widens what the walls allow; it is the memory view of the walls of AIP-34, and "What sealed guarantees" there holds for memory by construction.

An item is in the projection of a session when all of these hold:

  1. it is in force (rules 10 and 11);
  2. node. It carries a node anchor and that node is in the session's nodes. An item with no node anchor is outside the projection of every session that has a node scope. In a session with no node scope the reverse holds: an item with a node anchor is outside it, and an item with none is judged by conditions 3 and 4 alone, as in section 9;
  3. anchors. It is tagged global or one of the session's other anchors (section 9). The node: and operator: tags do not count as anchors for this condition and for the "no anchor tag is global" default. The conditions are an intersection: an anchor, global and an AIP-42 memory.anchors entry included, never admits an item that condition 2 excludes;
  4. ownership. If it carries an operator anchor, the session runs that operator, or the store's AIP-38 read grant on that anchor reaches the session. A grant extends condition 4 only. It never extends condition 2, so sharing an operator's memory does not cross a wall.

An operator's own item is therefore visible in a session only if the session's projection also includes the item's node. An item owned by an operator on a node outside the chain of the session is absent from that session, however the session was started and whoever owns the item.

global is tree-root scope. In a call with a node scope, global means the root node of the session's tree: an item tagged global carries the node anchor of that root (rule 33). Because the projection holds the root only when no sealed or hard node cuts the chain below it, a global item of one tree is never in a projection of another tree, and is not in the projection of a session inside a sealed node.

Writes, promotion and siblings

Store rules, continuing the numbering of section 8:

  1. Projection on every operation. Given a scope, a store MUST apply the node projection to list, search, read, propose, commit, supersede, archive and dismiss, and to the listing of proposals. An item outside it is not listed, not found by search, not readable, and not changeable.
  2. Outside is not found. read, supersede, archive and dismiss on an item or proposal outside the projection MUST fail with the same not-found error as an absent one, so a session cannot learn that an item exists on a node it cannot see.
  3. Filter first. list and search MUST apply the projection before pagination, limit, ranking and the building of snippets. A store that delegates search to an AIP-10 knowledge provider MUST either run the provider over an index restricted to the projection, or not delegate that call; checking hits afterwards (rule 22) is not enough, because it would rank and excerpt text the session may not see.
  4. Scope comes from the caller. The host builds the scope from the calling session, as AIP-34 requires, and a store MUST NOT take it from its own configuration. A call whose caller cannot be identified is refused by the host before it reaches the store. A call with no scope is a host call: it reads and writes as the host, for an export, an erasure at the principal's request, a migration or a clerk pass. A host MUST NOT give a session a store handle, a tool or a route that makes host calls.
  5. Write defaults. On a propose or commit with a non-empty scope.nodes, a store MUST add the node anchor scope.nodes[0] (the session's own node) when the document has none, and the operator anchor scope.operator when the session runs an operator and the document has none (rule 32). A node anchor, named by the writer or added, MUST be in scope.nodes; any other is a validation error naming tags. A captured proposal gets the same defaults (section 9).
  6. Ownership is the default, node-shared is a choice. A write by a session that runs an operator is owned by that operator. A writer that means the item for every operator of the node passes owner: "node", and the store then adds no operator anchor. A writer MUST NOT name an operator anchor other than scope.operator.
  7. Untagged writes are refused. A host call that creates an item or a proposal with no node anchor, on a store whose host declares trees, MUST be rejected with a validation error naming tags. A document tagged global in a call with a non-empty scope.nodes MUST carry the node anchor scope.tree, which the store adds when absent and which MUST be in scope.nodes; any other node anchor with global is a validation error. A session with an empty scope.nodes writes without a node anchor, as before.
  8. Promotion is an explicit re-tag. An item moves to an ancestor node only when a commit replaces its node anchor with another node of scope.nodes, carrying the ifRevision of rule 17 and allowed by the write policy of rule 21. A commit that sets a node anchor outside scope.nodes MUST be rejected. A re-tag changes neither the operator anchor nor the item's other anchors, and never reaches above a sealed or hard node: what leaves such a node does so through its EXPORT.md and matching exports (AIP-34), not through memory. Nothing promotes an item by itself: not a lifetime, not a clerk pass, not a read.
  9. Siblings never come in by projection. An item of a sibling node, of a descendant, or of another tree is never in a projection. A host MAY offer a cross-node query as a separate, explicit operation. It MUST check the caller against the queried node (the caller is a member of that node, by an AIP-22 seat, an AIP-34 agents entry or an AIP-38 grant), MUST honour the walls of AIP-34 (a sealed or hard node answers only with what it exports), SHOULD be rate-limited, MUST restrict the answer to the queried node's items that pass conditions 1 and 4 for the caller, and MUST NOT feed the answer into a digest. It answers the one query asked; it does not widen later projections.

The digest of section 9, the native-dir projection and its capture, and every tool the host exposes over the store (in the reference implementation memory_search, memory_list, memory_read, memory_write and the others) read and write through these rules. A native memory location is shared by the sessions that read it, so a host MUST NOT write the items of one node into a native location that a session outside that node's projection reads.

Rationale

  • Own doctype, AIP-10 base fields. Folding memory into AIP-10 would force a lifecycle and a principal scope onto a wiki that does not need them; reusing its five base fields keeps one listing and one slug convention across the memory layer.
  • Legacy fields kept. Writers already have items on disk keyed by id/name/type; the schema accepts them so no migration is needed to adopt the doctype.
  • Three statuses. The draft enum also listed the proposal states (proposed, confirmed, rejected, expired, stale). Those belong to the proposal ledger that precedes an item, not to a stored item.
  • No anchors array. Scope anchors already travel in tags in formatted form; a second structured copy invites drift. The structured anchor survives where it carries meaning, in lifetime.anchor.
  • capture apart from provenance. Where a claim was observed and which component wrote it down are different questions; a batch pass re-reading an old transcript has one provenance and a later capture.
  • Files as the source of truth. Every harness and store can read a directory of markdown files; an index can be rebuilt from them, the reverse is not true. Search is delegated to whatever knowledge provider the host already runs instead of being specified twice.
  • Compare-and-set over last writer wins. Two writers of one item (a clerk pass and a human) are expected, not rare; a revision check turns a lost update into a visible conflict at the cost of one re-read.
  • Proposals apart from items. Captured and extracted claims are untrusted until a policy-bound writer commits them; keeping them out of items/ means no reader, digest or search can mistake one for an item in force.
  • Native first, system prompt as fallback. As in AIP-71, a harness that reads its own memory location gets items where it already looks, and its own writes there can be captured; every other harness still gets the same digest through the system prompt, and never both.
  • A host-chosen digest bound. Context budgets differ per harness and per model; the spec fixes the order items are cut in (from the end of the section 9 order), that only whole items are cut, and that the cut is announced, not the number.
  • Node anchor for visibility, operator anchor for ownership. One anchor cannot do both. If ownership widened visibility, an operator would carry its own items into any session it runs, a company's session would be shown a personal tree's facts, and a wall would hold for everyone except the one principal that crosses it. So the node anchor decides where an item can be seen, the operator anchor decides whose it is, and an operator's own item needs both to pass.
  • The projection is a conjunct, not another anchor. Anchors in section 9 only select; a node condition that was one more anchor to match could be satisfied by global alone. Making it a condition every item must pass is what lets global mean the root of a tree instead of every tree.
  • Fail closed on untagged items. Items written before node anchors exist have none. A node-scoped session does not see them until a host call tags them, because the alternative, treating them as global, would put a sealed node's old items into every prompt of the tree.
  • The store applies the projection, the host builds it. The host already owns the tree, the walls and the caller (AIP-34); a store that re-derived them from its own configuration would serve many sessions with one scope. Passing the computed chain keeps the store small and its rule testable on a plain list.
  • Siblings by query, not by projection. A projection is read by every turn without anyone asking; a sibling guild's notes are reached on purpose, checked against membership and the walls, and rate-limited.
  • Status-only rewrites keep updated_at. Retiring an item does not change what it says; keeping the timestamp lets a reader sort by content age, and lets the store rewrite one line.

Reference Implementation

The reference implementation lives in agentproto/ts. It covers the document, the store, a daemon tool surface, a spawn-time digest, and the native-dir projection and capture for one harness.

Document (sections 1 to 7). @agentproto/memory provides defineMemory (the writer path: validates in canonical mode, fills status: active and an empty body, returns a frozen handle), validateMemory (each issue carries the rule it breaks; legacy items pass unless canonical mode is asked for), parseMemory, renderMemory (validates, double-quotes every string, keeps key order) and the lifecycle helpers memoryStatus, isAllowedStatusTransition and isInForce. It enforces rules 1, 2, 4, 5, 9, 10 and 12 and the until part of rule 11 on one document, and rule 3 through the renderer. Rule 8 yields warnings only. Rules 6 and 7, and the while and session parts of rule 11, need a second version of an item or outside context; they are left to the store and the host.

Store (section 8). The same package exports the MemoryStore port (write, read, list, search, supersede, archive, dismiss), the typed errors (MemoryConflictError, MemoryNotFoundError, MemoryTransitionError, MemorySlugTakenError; an invalid document raises MemoryValidationError naming the field) and FilesMemoryStore, the files-backed store over the reference layout. It covers rules 13 to 22:

  • revision is the SHA-256 of the file bytes and every change of an existing item needs the current ifRevision (rule 17); an equal re-write is a no-op (rule 18); updated_at is set on a content change only (rules 6 and 19).
  • supersede and archive rewrite only the status line (adding it when absent), commit the new item before retiring the old one, refuse any status change through commit, and nothing deletes an item file (rules 15, 16 and 20).
  • A slug is unique among active items (rule 14); a proposal is keyed by the hash of its rendered document and becomes an item only through a commit that names it with fromProposal (rule 21).
  • search is a weighted term match over the in-force items. It takes an optional knowledge provider through a structural interface; a hit that names an item the filter excludes is dropped, and any other hit is returned as source: "knowledge" (rule 22).

Writes use a temporary file and a rename and are serialized within one store instance. Several processes writing one directory are not coordinated.

Daemon tools and digest (sections 8 and 9, system prompt path). @agentproto/runtime keeps one FilesMemoryStore per resolved root (config key memory.root, overridden by an AIP-42 memory.store that names a files root) and registers the tools memory_search, memory_list, memory_read, memory_write (default mode propose), memory_supersede, memory_archive and memory_dismiss. Store errors become structured tool errors (conflict, not_found, invalid_transition, slug_taken, validation). The write policy of rule 21 is a role gate: the operator and supervisor sessions may commit, supersede, archive and dismiss; any other session, or one with no recorded role, can only propose; a session whose agent sets memory.enabled: false writes nothing while reads still work.

At spawn, when the agent manifest's memory block states a binding (enabled: true, store or anchors), the runtime appends the digest as one delimited block that presents the items as recorded data. It selects in-force items by the global tag or the session's anchors (session:, agent:, project: and the manifest's), orders them as the Digest subsection says, bounds the block at 4000 characters, cuts whole items and ends with the count left out and the tool to reach them. It covers rules 23, 25 and 26. A store read failure is a spawn warning, never a spawn failure.

Native projection and capture (section 9). @agentproto/harness implements the native-dir path (native-memory.ts) and the claude-code harness declares capabilities.memory { inject: "native-dir", capture: "native-dir-diff" }:

  • Projection writes one topic file per in-force item, carrying id, slug and a content hash in its frontmatter, and rewrites only a fenced, bounded block at the top of the native index. Native files and native index lines are never touched. It is idempotent and returns a snapshot that is persisted beside the session cache.
  • The path falls back to the system prompt digest, never both, when the harness's automatic memory is disabled, when the project sets its own memory directory, or when the config directory is the user's real one (rule 25).
  • Capture runs on the daemon's session event bus at turn-end and at exit, diffs the native location against the snapshot, and writes proposals only (rule 24): a new or changed native file becomes a new item, an edited projected file becomes the same id with the new content, a deleted projected file becomes the same id with status: archived. Each carries capture.mode: live, provenance.source: native-memory and the session id. Output passes validateMemory.

Known gaps. The node and operator anchors, the scope of every store operation and the node projection (section 10) are specified here and not implemented yet: the reference store, the daemon tools and the digest select by global and the session's own anchors only, and the tools call the store without a scope. A harness that declares inject: none, or declares nothing, still receives the system prompt digest when the manifest opts in, which is wider than the resolution order of section 9 (step 3). A bare store id in memory.store has no resolver yet and uses the default root with a spawn warning. Sandbox sessions get no native projection and no capture. Sessions started by the application runner get no digest.

Backwards Compatibility

Not applicable (new spec). Items written before the canonical fields existed validate through the legacy branch (section 2). Items written with empty provenance.sessionId or provenance.ref, or with the anchors array or the source/ts/hash capture of the pending draft, do not validate and need a rewrite.

The store and the projection (sections 8 and 9) are additive. A harness manifest without capabilities.memory keeps loading and reads as { inject: "none", capture: "none" }.

Section 10 is additive too. A host with no declared tree passes no scope with node anchors and keeps the behaviour of sections 8 and 9, and every session it serves has an empty projection. Where trees are declared, items written before node anchors exist have none and are outside the projection of every node-scoped session until a host call tags them (rule 33 refuses an untagged write, not an untagged item already on disk). The tags and lifetime.anchor values node and operator are new; a reader that does not know them MUST NOT show the item to a node-scoped session.

Security Considerations

  • Context injection. Memory items are read back into an agent's context. A writer MUST route item creation through the host's write policy; an item whose claim comes from untrusted input (a transcript, a fetched page) is attacker-controlled text. provenance and evidence.trust let a reader weigh it.
  • Personal data. user items describe a person. A store SHOULD let the principal list and erase their items; erasure on request overrides the "retire, do not delete" rule of section 3.
  • Projected text. The digest and the native memory location are read by the model as context. A host MUST present digest items as recorded data, MUST project only the items scoped to that session, and MUST NOT write the items of one principal into a native location another principal's sessions read.
  • Memory crossing a wall. An item reaches a session only if the session's node projection includes the item's node (section 10), and an operator's ownership of an item does not change that. The guarantee is the one of AIP-34, "What sealed guarantees": it covers what the host composes into a prompt, a projection and a tool answer. It is not an OS wall: a harness with native file tools, or an unconfined command tool, runs as the same OS user and can read memory files on disk, and a local process can claim another session's id. A host that needs more makes the node hard.
  • Captured text. Whatever a session writes into its native memory may come from untrusted input it processed; this is why a capture only ever proposes (rule 24).
  • Secrets. A writer MUST NOT store a secret value in any field or in the body, including inside provenance.quote.

See also

Resources

Supporting artifacts for AIP-72. Links open the file on GitHub — markdown and JSON render natively in GitHub's viewer. Browse the full resource tree →