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.
| Field | Value |
|---|---|
| AIP | 72 |
| Title | MEMORY (memory/v1): typed memory items about a principal and its work |
| Status | Draft |
| Type | Schema |
| Doctype | memory/v1 (one memory item, written as a markdown file with YAML frontmatter) |
| Requires | AIP-1, AIP-2, AIP-10 (base fields, knowledge providers), AIP-45 (the projection declaration) |
| Composes with | AIP-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) |
| Created | 2026-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
| Field | Type | Required | Meaning |
|---|---|---|---|
schema | "memory/v1" | canonical | Doctype discriminator. |
slug | string, ^[a-z][a-z0-9-]*[a-z0-9]$, 2 to 96 chars | canonical | Stable kebab-case identifier (AIP-10). |
kind | string, ^[a-z][a-z0-9-]*$ | canonical | AIP-10 spelling of the item type; one of user, feedback, project, reference for a memory/v1 item. |
title | string, 1 to 200 chars | canonical | Human-readable title (AIP-10). |
updated_at | ISO 8601 date-time | canonical | Last content write (rule 6). |
id | string | legacy | Store identifier (e.g. mem_qc8f407g). |
name | string, up to 1000 chars | legacy | Slugified name, kept apart from slug for round-trip. |
type | user | feedback | project | reference | legacy | The closed memory type. |
description | string, up to 4000 chars | no | One-line summary, independent of the body. |
tags | string[] | no | Free labels; scope anchors in formatted form (global, project:<slug>, agent:<slug>, pr:<owner>/<repo>#<n>, and, section 10, node:<id> and operator:<id>). |
polarity | do | dont | no | Feedback polarity; only on feedback items. |
lifetime | object | no | How long the item holds (section 4). |
status | active | superseded | archived | no | Lifecycle (section 3); absent means active. |
created | ISO 8601 date-time | no | Creation time. |
written | ISO 8601 date-time | no | Legacy mirror of updated_at. |
decidedBy | { rule, source } | no | The rule that decided the item, and where that rule came from. |
provenance | object | no | Where the claim was observed (section 5). |
capture | object | no | Who and how captured it (section 5). |
evidence | object | no | Trust 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
└─────> archivedA 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
kind | Extra field | Holds |
|---|---|---|
durable | none | until retired |
until | at (date-time), REQUIRED | until at |
while | anchor, REQUIRED | as long as the anchor holds (a task open, a PR open...) |
session | none | for 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:
- 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. - When both
kindandtypeare present they MUST be equal. - Every string-typed field MUST be written so a YAML 1.2 parser reads a
string: a value such as
true,null,noor2026MUST be quoted. - An optional field with no value MUST be omitted, never written empty
(in particular
provenance.sessionIdandprovenance.ref). polarityMUST NOT be set on an item whose type is notfeedback.- A writer MUST set
updated_atwhen it creates the item and when it changes any field other thanstatus. A status-only rewrite MAY leaveupdated_atunchanged, and MUST leave every other byte of the file unchanged. - A writer MUST only move
statusfromactive(or absent) tosupersededorarchived, and MUST NOT move it out of either. - A writer SHOULD record
provenance.source,provenance.atand, when the claim comes from a quotable source,provenance.quoteverbatim.
Reader rules:
- A reader MUST accept both canonical and legacy items (section 2), and
MUST treat an absent
statusasactive. - A reader MUST NOT present a
supersededorarchiveditem as being in force; it MAY show it as history. - A reader SHOULD treat an
activeitem whose lifetime no longer holds (anuntilpast itsat, awhilewhose anchor is gone, asessionitem outside its session) as not in force, even before a writer archives it. - 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.
proposerecords a proposal: amemory/v1document that is not an item yet, is not in force, and is never projected into a session.commitcreates the item, or replaces the content of an existing one. - read one item by
id. A lookup byslugis alistwith theslugfilter, 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: trueit 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 itsid) 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
statusbecomessuperseded. The old item stays readable. - archive an item: its
statusbecomesarchived. 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 itemsThe 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:
- 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.
- An
idMUST identify at most one item in a store, across all types; a commit that changes an item'stypemoves the item and never leaves two files for oneid. Aslug, 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. - A store MUST only change
statusfromactivetosuperseded(through supersede) or toarchived(through archive), and MUST reject a commit that would move an item out ofsupersededorarchived(rule 7). An item replaced in substance is superseded under a newid, not rewritten in place. - 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.
- Writes use compare-and-set. A commit that would change an existing
item, a supersede and an archive MUST carry the
ifRevisionthe 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. - A write is idempotent by
id: a commit whose item equals the stored one in every field butupdated_atandwritten, body included, succeeds without touching the file and returns the current revision, with or withoutifRevision. A propose of a document already pending returns the existing proposal. - On a commit that creates an item or changes any field other than
status, the store MUST setupdated_at(andwritten, when the item carries it) to the commit time. Supersede and archive are status-only rewrites: they MUST leaveupdated_atand every other byte of the file unchanged (rule 6). - 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
idfrom 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 laterupdated_at. - 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
fromProposaldrops that proposal once the item is written. - 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-dirmeans the harness reads a native memory directory or file at start, and the harness can write items into it.inject: system-promptmeans the harness has no native memory but accepts appended system-prompt text at spawn.inject: nonemeans neither.capture: native-dir-diffmeans 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:
- When the harness declares
inject: native-dirand the host implements the native projection for that harness, the digest is written into the native location. - Otherwise, when the harness declares
native-dirorsystem-promptand the host can append to that session's system prompt, the digest is appended to the system prompt. - 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,slugwhen present, andtitle;polarity, on afeedbackitem;descriptionwhen 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:
| Difference | Proposal |
|---|---|
| a new entry | a new item |
| a changed projected item | the same id with the new content |
| a removed projected item | the 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:
- A host MUST NOT project a proposal, or an item that is not in force.
- A host MUST NOT commit a captured change; it MUST write it as a proposal.
- A host MUST NOT inject the same items through more than one path in one session.
- 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 }, formattednode:<id>.idis the AIP-34idof 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 }, formattedoperator:<id>.idis the operator body of an AIP-54operator: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:
- it is in force (rules 10 and 11);
- 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; - anchors. It is tagged
globalor one of the session's other anchors (section 9). Thenode:andoperator:tags do not count as anchors for this condition and for the "no anchor tag isglobal" default. The conditions are an intersection: an anchor,globaland an AIP-42memory.anchorsentry included, never admits an item that condition 2 excludes; - 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:
- Projection on every operation. Given a
scope, a store MUST apply the node projection tolist,search,read,propose,commit,supersede,archiveanddismiss, and to the listing of proposals. An item outside it is not listed, not found by search, not readable, and not changeable. - Outside is not found.
read,supersede,archiveanddismisson 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. - Filter first.
listandsearchMUST apply the projection before pagination,limit, ranking and the building of snippets. A store that delegatessearchto 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. - Scope comes from the caller. The host builds the
scopefrom 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 noscopeis 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. - Write defaults. On a
proposeorcommitwith a non-emptyscope.nodes, a store MUST add the node anchorscope.nodes[0](the session's own node) when the document has none, and the operator anchorscope.operatorwhen the session runs an operator and the document has none (rule 32). A node anchor, named by the writer or added, MUST be inscope.nodes; any other is a validation error namingtags. A captured proposal gets the same defaults (section 9). - 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 thanscope.operator. - 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 taggedglobalin a call with a non-emptyscope.nodesMUST carry the node anchorscope.tree, which the store adds when absent and which MUST be inscope.nodes; any other node anchor withglobalis a validation error. A session with an emptyscope.nodeswrites without a node anchor, as before. - 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 theifRevisionof rule 17 and allowed by the write policy of rule 21. A commit that sets a node anchor outsidescope.nodesMUST 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 itsEXPORT.mdand matchingexports(AIP-34), not through memory. Nothing promotes an item by itself: not a lifetime, not a clerk pass, not a read. - 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
agentsentry 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
anchorsarray. Scope anchors already travel intagsin formatted form; a second structured copy invites drift. The structured anchor survives where it carries meaning, inlifetime.anchor. captureapart fromprovenance. 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
globalalone. Making it a condition every item must pass is what letsglobalmean 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:
revisionis the SHA-256 of the file bytes and every change of an existing item needs the currentifRevision(rule 17); an equal re-write is a no-op (rule 18);updated_atis set on a content change only (rules 6 and 19).supersedeandarchiverewrite only thestatusline (adding it when absent), commit the new item before retiring the old one, refuse any status change throughcommit, 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
committhat names it withfromProposal(rule 21). searchis 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 assource: "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,slugand 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-endand 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 sameidwith the new content, a deleted projected file becomes the sameidwithstatus: archived. Each carriescapture.mode: live,provenance.source: native-memoryand the session id. Output passesvalidateMemory.
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.
provenanceandevidence.trustlet a reader weigh it. - Personal data.
useritems 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
sealedguarantees": 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 nodehard. - 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
- AIP-9 OPERATOR: the operator whose memory carries the operator anchor
- AIP-10 KNOWLEDGE: the base fields, and the sibling doctype for curated knowledge
- AIP-11 LESSON: distilled lessons
- AIP-34 WORKSPACE: nodes, walls, and the node scope of a session
- AIP-45 HARNESS:
capabilities.memory, the projection declaration - AIP-68 CLERK: the secretary that promotes proposals into items
- AIP-71 ACTION-HOOKS: the native first pattern the projection follows
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 →
AIP-71: ACTION-HOOKS (action-hooks/v1): portable action hooks and native harness projections
Defines three hook paths over AIP-37 lifecycle events and AIP-39 actions, plus a native-first harness projection contract that uses harness hooks when available and a host runtime fallback otherwise without double execution.
AIP-73: TUNNEL (tunnel/v1): the tunnel provider contract
Fixes the contract a tunnel provider implements to give a locally running service a stable public URL: the TunnelProvider interface (create, list, delete, status, health) with its idempotency rules, the three authentication modes (apiKey, token, oidc), the per-slug credential store under ~/.agentproto/tunnel-creds with its file modes, provider discovery and registration, the lifecycle from setup to delete, the v1 HTTP contract of a remote provisioner (GET/PUT/DELETE /v1/tunnels), and the security and conformance rules.