@agentproto/memory 0.0.0 → 0.1.0

package/dist/index.mjs

@@ -1,6 +1,9 @@
 import { createDoctype } from '@agentproto/doctype';
 import { z } from 'zod';
 import { parseDocument, stringify } from 'yaml';
+import { randomBytes, createHash } from 'crypto';
+import { unlink, mkdir, rename, writeFile, readFile, readdir } from 'fs/promises';
+import { join } from 'path';
 
 /**
  * @agentproto/memory
@@ -29,7 +32,7 @@ var MemoryParseError = class extends Error {
     this.name = "MemoryParseError";
   }
 };
-var memoryFrontmatterSchema = z.object({ "schema": z.literal("memory/v1").describe("Discriminator for a memory/v1 document. Optional only to tolerate legacy items written before this doctype existed; a canonical memory/v1 document MUST set it, and when present it MUST equal 'memory/v1'.").optional(), "slug": z.string().regex(new RegExp("^[a-z][a-z0-9-]*[a-z0-9]$")).min(2).max(96).describe("Stable kebab-case identifier (AIP-10 convention). Used as the item's path stem and cross-reference target.").optional(), "kind": z.string().regex(new RegExp("^[a-z][a-z0-9-]*$")).min(2).max(32).describe("Item kind (AIP-10 convention). Common values are the memory types: 'user', 'feedback', 'project', 'reference'.").optional(), "title": z.string().min(1).max(200).describe("Human-readable title (AIP-10 convention).").optional(), "updated_at": z.string().datetime({ offset: true }).describe("ISO 8601 timestamp of the last content write (AIP-10 convention). A writer MUST set it when it creates the item and when it changes any field other than `status`; a status-only lifecycle rewrite (to `superseded` or `archived`) MAY leave it unchanged.").optional(), "id": z.string().min(1).describe("Item identifier (e.g. 'mem_qc8f407g'). Legacy alias for the AIP-10 path stem; when the base fields are omitted it takes part in identifying the item.").optional(), "name": z.string().min(1).max(1e3).describe("Slugified name, distinct from `title`. Kept as a separate field so a legacy item round-trips without loss.").optional(), "type": z.enum(["user", "feedback", "project", "reference"]).describe("Memory type. The closed type set from the memory contract; `kind` is the AIP-10-aligned spelling of the same notion.").optional(), "description": z.string().max(4e3).describe("One-line human-readable summary, independent of the body.").optional(), "tags": z.array(z.string().min(1)).describe("Free-form labels. Scope anchors are carried here in their formatted form (e.g. 'global', 'project:fhcm', 'agent:assistant', 'pr:agentproto/ts#1858').").default([]), "polarity": z.enum(["do", "dont"]).describe("Feedback polarity. Present only on items of type 'feedback'.").optional(), "lifetime": z.object({ "kind": z.enum(["durable", "until", "while", "session"]).describe("Lifetime kind. 'durable' never expires; 'until' expires at `at`; 'while' lasts as long as `anchor` holds; 'session' lasts for the session."), "at": z.string().datetime({ offset: true }).describe("Expiry timestamp for kind 'until'.").optional(), "anchor": z.object({ "kind": z.enum(["global", "project", "task", "session", "pr", "contact", "agent"]).describe("Anchor kind. 'agent' extends the conversation-contract set for per-agent anchoring."), "slug": z.string().min(1).describe("Anchor target slug (project, contact, agent).").optional(), "id": z.string().min(1).describe("Anchor target id (task, session).").optional(), "repo": z.string().min(1).describe("Repository 'owner/name' for a pr anchor.").optional(), "number": z.number().int().gte(1).describe("Pull-request number for a pr anchor.").optional() }).strict().describe("Governing anchor for kind 'while'.").optional() }).strict().and(z.intersection(z.any(), z.any())).describe("How long the item stays valid. Typical values are { kind: 'durable' } or { kind: 'while', anchor: { \u2026 } }.").optional(), "status": z.enum(["active", "superseded", "archived"]).describe("Lifecycle status. A writer creates an item 'active'. 'superseded' means a newer item replaces it; 'archived' means it is retired without a replacement (decayed, or its anchor no longer resolves). Both are terminal: an item is marked, never erased. Absent means 'active'.").optional(), "created": z.string().datetime({ offset: true }).describe("Creation timestamp.").optional(), "written": z.string().datetime({ offset: true }).describe("Last-write timestamp. Mirrors the AIP-10 `updated_at`.").optional(), "decidedBy": z.object({ "rule": z.string().min(1).describe("Classifier rule that produced the item (e.g. 'lens-confident', 'brain-memory-file').").optional(), "source": z.string().min(1).describe("Where the deciding rule came from (e.g. 'builtin').").optional() }).strict().describe("Which classifier/rule decided the item's shape and status.").optional(), "provenance": z.object({ "source": z.string().min(1).describe("Provenance source class (e.g. 'brain-transcript', 'brain-memory-file', 'converse', 'task-close', 'recall-gap').").optional(), "sessionId": z.string().min(1).describe("Session the claim was observed in. Omitted, never empty, when the source has no session.").optional(), "ref": z.string().min(1).describe("Opaque reference into the source (message uuid, file path, ...). Omitted, never empty, when the source has none.").optional(), "quote": z.string().describe("Verbatim quote backing the claim.").optional(), "at": z.string().datetime({ offset: true }).describe("When the claim was observed.").optional(), "extractorVersion": z.string().min(1).describe("Identifier and version of the extractor that produced the claim (e.g. 'lens@3'), so a reader can tell items from different extractor generations apart.").optional() }).strict().describe("Origin of the item's claims.").optional(), "evidence": z.object({ "sourceKind": z.string().min(1).describe("Kind of source the evidence came from (e.g. 'brain-transcript', 'brain-memory-file').").optional(), "trust": z.string().min(1).describe("Trust class of the source (e.g. 'jeremy', 'internal').").optional(), "explicitness": z.string().min(1).describe("Whether the claim was stated outright or inferred (e.g. 'implicit', 'explicit').").optional(), "corroborations": z.number().int().gte(0).describe("Number of independent corroborating observations.").optional(), "contradictsActive": z.boolean().describe("True when this item contradicts an active item.").optional(), "impact": z.string().min(1).describe("Impact class of the item (e.g. 'low', 'high').").optional(), "lifetime": z.object({ "kind": z.enum(["durable", "until", "while", "session"]).describe("Lifetime kind. 'durable' never expires; 'until' expires at `at`; 'while' lasts as long as `anchor` holds; 'session' lasts for the session."), "at": z.string().datetime({ offset: true }).describe("Expiry timestamp for kind 'until'.").optional(), "anchor": z.object({ "kind": z.enum(["global", "project", "task", "session", "pr", "contact", "agent"]).describe("Anchor kind. 'agent' extends the conversation-contract set for per-agent anchoring."), "slug": z.string().min(1).describe("Anchor target slug (project, contact, agent).").optional(), "id": z.string().min(1).describe("Anchor target id (task, session).").optional(), "repo": z.string().min(1).describe("Repository 'owner/name' for a pr anchor.").optional(), "number": z.number().int().gte(1).describe("Pull-request number for a pr anchor.").optional() }).strict().describe("Governing anchor for kind 'while'.").optional() }).strict().and(z.intersection(z.any(), z.any())).describe("Lifetime as computed for the evidence pass.").optional(), "anchorsResolved": z.array(z.string().min(1)).describe("Resolved anchor labels in their formatted form (e.g. 'global', 'project:fhcm', 'pr:agentproto/ts#1858', 'session:sess_\u2026').").default([]), "ageHours": z.number().describe("Age of the evidence in hours (may be fractional or negative relative to the write clock).").optional(), "flags": z.array(z.string().min(1)).describe("Machine-stable flags raised during the evidence pass.").default([]) }).strict().describe("Trust/impact accounting captured at write time.").optional(), "capture": z.object({ "mode": z.enum(["live", "batch"]).describe("How the item was captured: 'live' during the session it describes, 'batch' by a later pass over stored transcripts or files.").optional(), "producer": z.string().min(1).describe("Who or what captured the item (e.g. a clerk lens, a migration, an importer). 'unknown' when the producer did not identify itself.").optional(), "capturedAt": z.string().datetime({ offset: true }).describe("ISO 8601 timestamp at which the source was captured or extracted.").optional() }).strict().describe("Who, what and how captured the item, kept apart from `provenance` (where the claim was observed).").optional(), "body": z.string().describe("Unrestricted markdown body of the MEMORY.md file. Not constrained by this schema.").optional() }).strict().and(z.union([z.any(), z.any()])).describe("Validates the YAML frontmatter of an AIP-72 memory/v1 item: one small typed assertion (user, feedback, project, reference) about a principal or its work, with a lifecycle. A third doctype in the memory layer: it neither absorbs nor replaces AIP-10 knowledge/v1 entries (curated, shareable wiki pages over immutable sources) nor AIP-11 lesson/v1 (distilled lessons from runs). A memory/v1 item carries the AIP-10 base fields (schema, slug, kind, title, updated_at); the remaining fields are the memory item shape and are OPTIONAL, so a writer that emits only the AIP-10 base fields and a writer that emits the full item both validate against the same schema. The markdown body (the `body` property) is unrestricted text.");
+var memoryFrontmatterSchema = z.object({ "schema": z.literal("memory/v1").describe("Discriminator for a memory/v1 document. Optional only to tolerate legacy items written before this doctype existed; a canonical memory/v1 document MUST set it, and when present it MUST equal 'memory/v1'.").optional(), "slug": z.string().regex(new RegExp("^[a-z][a-z0-9-]*[a-z0-9]$")).min(2).max(96).describe("Stable kebab-case identifier (AIP-10 convention). Used as the item's path stem and cross-reference target.").optional(), "kind": z.string().regex(new RegExp("^[a-z][a-z0-9-]*$")).min(2).max(32).describe("Item kind (AIP-10 convention). Common values are the memory types: 'user', 'feedback', 'project', 'reference'.").optional(), "title": z.string().min(1).max(200).describe("Human-readable title (AIP-10 convention).").optional(), "updated_at": z.string().datetime({ offset: true }).describe("ISO 8601 timestamp of the last content write (AIP-10 convention). A writer MUST set it when it creates the item and when it changes any field other than `status`; a status-only lifecycle rewrite (to `superseded` or `archived`) MAY leave it unchanged.").optional(), "id": z.string().min(1).describe("Item identifier (e.g. 'mem_qc8f407g'). Legacy alias for the AIP-10 path stem; when the base fields are omitted it takes part in identifying the item.").optional(), "name": z.string().min(1).max(1e3).describe("Slugified name, distinct from `title`. Kept as a separate field so a legacy item round-trips without loss.").optional(), "type": z.enum(["user", "feedback", "project", "reference"]).describe("Memory type. The closed type set from the memory contract; `kind` is the AIP-10-aligned spelling of the same notion.").optional(), "description": z.string().max(4e3).describe("One-line human-readable summary, independent of the body.").optional(), "tags": z.array(z.string().min(1)).describe("Free-form labels. Scope anchors are carried here in their formatted form (e.g. 'global', 'project:acme', 'agent:assistant', 'pr:acme/app#42'). Two anchors tie an item to an AIP-34 tree and an AIP-9 operator: 'node:<id>' (the AIP-34 node id, e.g. 'node:@acme/agentik') scopes visibility, and 'operator:<id>' (e.g. 'operator:pm-simone') marks ownership and never widens visibility. An item carries at most one of each; the node projection and write rules are in AIP-72 section 10.").default([]), "polarity": z.enum(["do", "dont"]).describe("Feedback polarity. Present only on items of type 'feedback'.").optional(), "lifetime": z.object({ "kind": z.enum(["durable", "until", "while", "session"]).describe("Lifetime kind. 'durable' never expires; 'until' expires at `at`; 'while' lasts as long as `anchor` holds; 'session' lasts for the session."), "at": z.string().datetime({ offset: true }).describe("Expiry timestamp for kind 'until'.").optional(), "anchor": z.object({ "kind": z.enum(["global", "project", "task", "session", "pr", "contact", "agent", "node", "operator"]).describe("Anchor kind. 'agent' extends the conversation-contract set for per-agent anchoring. 'node' names an AIP-34 node and scopes visibility; 'operator' names an AIP-9 operator and marks ownership (AIP-72 section 10)."), "slug": z.string().min(1).describe("Anchor target slug (project, contact, agent).").optional(), "id": z.string().min(1).describe("Anchor target id (task, session, node, operator). For a node, the AIP-34 id ('@<owner>/<slug>'); for an operator, the operator body of an AIP-54 'operator:' ref ('<slug>' or '<slug>@<workspace>').").optional(), "repo": z.string().min(1).describe("Repository 'owner/name' for a pr anchor.").optional(), "number": z.number().int().gte(1).describe("Pull-request number for a pr anchor.").optional() }).strict().describe("Governing anchor for kind 'while'.").optional() }).strict().and(z.intersection(z.any(), z.any())).describe("How long the item stays valid. Typical values are { kind: 'durable' } or { kind: 'while', anchor: { \u2026 } }.").optional(), "status": z.enum(["active", "superseded", "archived"]).describe("Lifecycle status. A writer creates an item 'active'. 'superseded' means a newer item replaces it; 'archived' means it is retired without a replacement (decayed, or its anchor no longer resolves). Both are terminal: an item is marked, never erased. Absent means 'active'.").optional(), "created": z.string().datetime({ offset: true }).describe("Creation timestamp.").optional(), "written": z.string().datetime({ offset: true }).describe("Last-write timestamp. Mirrors the AIP-10 `updated_at`.").optional(), "decidedBy": z.object({ "rule": z.string().min(1).describe("Classifier rule that produced the item (e.g. 'classifier-confident', 'memory-file').").optional(), "source": z.string().min(1).describe("Where the deciding rule came from (e.g. 'builtin').").optional() }).strict().describe("Which classifier/rule decided the item's shape and status.").optional(), "provenance": z.object({ "source": z.string().min(1).describe("Provenance source class (e.g. 'transcript', 'memory-file', 'converse', 'task-close', 'recall-gap').").optional(), "sessionId": z.string().min(1).describe("Session the claim was observed in. Omitted, never empty, when the source has no session.").optional(), "ref": z.string().min(1).describe("Opaque reference into the source (message uuid, file path, ...). Omitted, never empty, when the source has none.").optional(), "quote": z.string().describe("Verbatim quote backing the claim.").optional(), "at": z.string().datetime({ offset: true }).describe("When the claim was observed.").optional(), "extractorVersion": z.string().min(1).describe("Identifier and version of the extractor that produced the claim (e.g. 'extractor@3'), so a reader can tell items from different extractor generations apart.").optional() }).strict().describe("Origin of the item's claims.").optional(), "evidence": z.object({ "sourceKind": z.string().min(1).describe("Kind of source the evidence came from (e.g. 'transcript', 'memory-file').").optional(), "trust": z.string().min(1).describe("Trust class of the source (e.g. 'owner', 'internal').").optional(), "explicitness": z.string().min(1).describe("Whether the claim was stated outright or inferred (e.g. 'implicit', 'explicit').").optional(), "corroborations": z.number().int().gte(0).describe("Number of independent corroborating observations.").optional(), "contradictsActive": z.boolean().describe("True when this item contradicts an active item.").optional(), "impact": z.string().min(1).describe("Impact class of the item (e.g. 'low', 'high').").optional(), "lifetime": z.object({ "kind": z.enum(["durable", "until", "while", "session"]).describe("Lifetime kind. 'durable' never expires; 'until' expires at `at`; 'while' lasts as long as `anchor` holds; 'session' lasts for the session."), "at": z.string().datetime({ offset: true }).describe("Expiry timestamp for kind 'until'.").optional(), "anchor": z.object({ "kind": z.enum(["global", "project", "task", "session", "pr", "contact", "agent", "node", "operator"]).describe("Anchor kind. 'agent' extends the conversation-contract set for per-agent anchoring. 'node' names an AIP-34 node and scopes visibility; 'operator' names an AIP-9 operator and marks ownership (AIP-72 section 10)."), "slug": z.string().min(1).describe("Anchor target slug (project, contact, agent).").optional(), "id": z.string().min(1).describe("Anchor target id (task, session, node, operator). For a node, the AIP-34 id ('@<owner>/<slug>'); for an operator, the operator body of an AIP-54 'operator:' ref ('<slug>' or '<slug>@<workspace>').").optional(), "repo": z.string().min(1).describe("Repository 'owner/name' for a pr anchor.").optional(), "number": z.number().int().gte(1).describe("Pull-request number for a pr anchor.").optional() }).strict().describe("Governing anchor for kind 'while'.").optional() }).strict().and(z.intersection(z.any(), z.any())).describe("Lifetime as computed for the evidence pass.").optional(), "anchorsResolved": z.array(z.string().min(1)).describe("Resolved anchor labels in their formatted form (e.g. 'global', 'project:acme', 'pr:acme/app#42', 'session:sess_\u2026').").default([]), "ageHours": z.number().describe("Age of the evidence in hours (may be fractional or negative relative to the write clock).").optional(), "flags": z.array(z.string().min(1)).describe("Machine-stable flags raised during the evidence pass.").default([]) }).strict().describe("Trust/impact accounting captured at write time.").optional(), "capture": z.object({ "mode": z.enum(["live", "batch"]).describe("How the item was captured: 'live' during the session it describes, 'batch' by a later pass over stored transcripts or files.").optional(), "producer": z.string().min(1).describe("Who or what captured the item (e.g. a clerk, a migration, an importer). 'unknown' when the producer did not identify itself.").optional(), "capturedAt": z.string().datetime({ offset: true }).describe("ISO 8601 timestamp at which the source was captured or extracted.").optional() }).strict().describe("Who, what and how captured the item, kept apart from `provenance` (where the claim was observed).").optional(), "body": z.string().describe("Unrestricted markdown body of the MEMORY.md file. Not constrained by this schema.").optional() }).strict().and(z.union([z.any(), z.any()])).describe("Validates the YAML frontmatter of an AIP-72 memory/v1 item: one small typed assertion (user, feedback, project, reference) about a principal or its work, with a lifecycle. A third doctype in the memory layer: it neither absorbs nor replaces AIP-10 knowledge/v1 entries (curated, shareable wiki pages over immutable sources) nor AIP-11 lesson/v1 (distilled lessons from runs). A memory/v1 item carries the AIP-10 base fields (schema, slug, kind, title, updated_at); the remaining fields are the memory item shape and are OPTIONAL, so a writer that emits only the AIP-10 base fields and a writer that emits the full item both validate against the same schema. The markdown body (the `body` property) is unrestricted text.");
 
 // src/types.ts
 var MEMORY_TYPES = ["user", "feedback", "project", "reference"];
@@ -247,10 +250,645 @@ function isInForce(doc, now = /* @__PURE__ */ new Date()) {
   return true;
 }
 
+// src/node-scope.ts
+var NODE_PREFIX = "node:";
+var OPERATOR_PREFIX = "operator:";
+function nodeTag(id) {
+  return `${NODE_PREFIX}${id}`;
+}
+function operatorTag(id) {
+  return `${OPERATOR_PREFIX}${id}`;
+}
+function idsOf(tags, prefix) {
+  const out = [];
+  for (const tag of tags ?? []) {
+    if (tag.startsWith(prefix) && tag.length > prefix.length) out.push(tag.slice(prefix.length));
+  }
+  return out;
+}
+function nodeAnchorIds(item) {
+  return idsOf(item.tags, NODE_PREFIX);
+}
+function operatorAnchorIds(item) {
+  return idsOf(item.tags, OPERATOR_PREFIX);
+}
+function isNodeOrOperatorTag(tag) {
+  return tag.startsWith(NODE_PREFIX) || tag.startsWith(OPERATOR_PREFIX);
+}
+function isInNodeProjection(item, scope, opts = {}) {
+  const nodes = nodeAnchorIds(item);
+  if (scope.nodes.length > 0) {
+    if (nodes.length === 0) return false;
+    if (!nodes.every((n) => scope.nodes.includes(n))) return false;
+  } else if (nodes.length > 0) {
+    return false;
+  }
+  const owners = operatorAnchorIds(item);
+  if (owners.length === 0) return true;
+  const granted = new Set(opts.grantedOperators ?? []);
+  return owners.every((o) => o === scope.operator || granted.has(o));
+}
+function refuse(rule, message) {
+  throw new MemoryValidationError("memory scope (AIP-72 section 10)", [
+    { path: "tags", message, rule }
+  ]);
+}
+function applyWriteScope(item, scope, opts = {}) {
+  const tags = item.tags ?? [];
+  const nodes = nodeAnchorIds(item);
+  const owners = operatorAnchorIds(item);
+  if (nodes.length > 1) refuse("rule-31", "an item carries at most one node anchor");
+  if (owners.length > 1) refuse("rule-32", "an item carries at most one operator anchor");
+  const basisNodes = opts.basis ? nodeAnchorIds(opts.basis) : [];
+  const basisOwned = opts.basis ? operatorAnchorIds(opts.basis).length > 0 : true;
+  const add = [];
+  if (scope === void 0) {
+    if (nodes.length === 0 && basisNodes[0] !== void 0) add.push(nodeTag(basisNodes[0]));
+    if (nodes.length === 0 && add.length === 0 && opts.declaresTrees) {
+      refuse("rule-33", "a document with no node anchor is refused where the host declares trees");
+    }
+    return add.length > 0 ? { ...item, tags: [...tags, ...add] } : item;
+  }
+  const inScope = new Set(scope.nodes);
+  for (const n of nodes) {
+    if (!inScope.has(n)) refuse("rule-31", `node anchor '${n}' is outside the session's node projection`);
+  }
+  if (scope.nodes.length > 0) {
+    if (tags.includes("global")) {
+      if (nodes.some((n) => n !== scope.tree)) {
+        refuse("rule-33", "a global item carries only the node anchor of the tree root");
+      }
+      if (nodes.length === 0) {
+        if (scope.tree === void 0 || !inScope.has(scope.tree)) {
+          refuse("rule-33", "the tree root is not in the session's node projection, so it cannot write a global item");
+        }
+        add.push(nodeTag(scope.tree));
+      }
+    } else if (nodes.length === 0) {
+      add.push(nodeTag(basisNodes[0] ?? scope.nodes[0]));
+    }
+  }
+  for (const o of owners) {
+    if (o !== scope.operator) refuse("rule-32", `operator anchor '${o}' is not the session's operator`);
+  }
+  if (owners.length > 0 && opts.owner === "node") {
+    refuse("rule-32", "owner 'node' and an operator anchor contradict each other");
+  }
+  if (owners.length === 0 && scope.operator !== void 0) {
+    const owner = opts.owner ?? (basisOwned ? "operator" : "node");
+    if (owner === "operator") add.push(operatorTag(scope.operator));
+  }
+  return add.length > 0 ? { ...item, tags: [...tags, ...add] } : item;
+}
+function assertRetagOnly(before, after) {
+  const was = nodeAnchorIds(before)[0];
+  const now = nodeAnchorIds(after)[0];
+  if (was === now) return;
+  const rest = (item) => [...new Set((item.tags ?? []).filter((t) => !t.startsWith(NODE_PREFIX)))].sort().join("\n");
+  if (rest(before) !== rest(after)) {
+    refuse("rule-34", "a re-tag moves the node anchor only: it changes neither the operator anchor nor the other anchors");
+  }
+}
+
+// src/store.ts
+var MemoryStoreError = class extends Error {
+  code;
+  constructor(code, message) {
+    super(`memory store (AIP-72): ${message}`);
+    this.name = "MemoryStoreError";
+    this.code = code;
+  }
+};
+var MemoryConflictError = class extends MemoryStoreError {
+  id;
+  /** The revision the caller sent, if any. */
+  expected;
+  /** The revision on disk, `undefined` when the item does not exist. */
+  actual;
+  constructor(id, expected, actual) {
+    super(
+      "conflict",
+      expected === void 0 ? `'${id}' exists: a write that changes it must carry ifRevision` : actual === void 0 ? `'${id}' does not exist, but ifRevision '${expected}' was given` : `'${id}' is at revision '${actual}', not '${expected}'`
+    );
+    this.name = "MemoryConflictError";
+    this.id = id;
+    this.expected = expected;
+    this.actual = actual;
+  }
+};
+var MemoryNotFoundError = class extends MemoryStoreError {
+  id;
+  what;
+  constructor(what, id) {
+    super("not-found", `no ${what} '${id}'`);
+    this.name = "MemoryNotFoundError";
+    this.id = id;
+    this.what = what;
+  }
+};
+var MemoryTransitionError = class extends MemoryStoreError {
+  id;
+  from;
+  to;
+  constructor(id, from, to, detail) {
+    super(
+      "invalid-transition",
+      `'${id}' cannot move from '${from}' to '${to}'${detail ? `: ${detail}` : ""}`
+    );
+    this.name = "MemoryTransitionError";
+    this.id = id;
+    this.from = from;
+    this.to = to;
+  }
+};
+var MemorySlugTakenError = class extends MemoryStoreError {
+  slug;
+  /** The active item holding it. */
+  holder;
+  constructor(slug, holder) {
+    super("slug-taken", `slug '${slug}' is held by active item '${holder}'`);
+    this.name = "MemorySlugTakenError";
+    this.slug = slug;
+    this.holder = holder;
+  }
+};
+var SAFE_ID = /^[A-Za-z0-9][A-Za-z0-9_.-]*$/;
+var PROPOSAL_ID = /^[a-f0-9]{64}$/;
+var ID_ALPHABET = "abcdefghijklmnopqrstuvwxyz0123456789";
+var DEFAULT_SEARCH_LIMIT = 20;
+var SNIPPET_CHARS = 160;
+var FilesMemoryStore = class {
+  #root;
+  #knowledge;
+  #now;
+  #declaresTrees;
+  #tail = Promise.resolve();
+  constructor(options) {
+    this.#root = options.root;
+    this.#knowledge = options.knowledge;
+    this.#now = options.now ?? (() => /* @__PURE__ */ new Date());
+    this.#declaresTrees = options.declaresTrees ?? false;
+  }
+  write(item, opts) {
+    return this.#exclusive(
+      () => opts.mode === "propose" ? this.#propose(item, opts) : this.#commit(item, opts)
+    );
+  }
+  async read(id, opts = {}) {
+    const stored = await this.#find(id);
+    return stored && visible(stored.record, opts.scope) ? stored.record : null;
+  }
+  async list(filter = {}) {
+    const stored = filter.proposals ? await this.#allProposals() : await this.#allItems();
+    const types = toArray(filter.type);
+    const statuses = toArray(filter.status);
+    const inForce = filter.inForce ?? (filter.status === void 0 && !filter.proposals ? true : void 0);
+    const now = this.#now();
+    let records = stored.map((s) => s.record).filter(({ item }) => {
+      if (types && !types.includes(itemType(item))) return false;
+      if (statuses && !statuses.includes(memoryStatus(item))) return false;
+      if (filter.slug !== void 0 && item.slug !== filter.slug) return false;
+      if (filter.tags && !filter.tags.some((t) => item.tags?.includes(t))) return false;
+      if (filter.scope && !isInNodeProjection(item, filter.scope)) return false;
+      if (inForce !== void 0) {
+        const holds = !filter.proposals && isInForce(item, now);
+        if (holds !== inForce) return false;
+      }
+      return true;
+    }).sort(byNewest);
+    if (filter.slug !== void 0 && !filter.proposals) {
+      const firstActive = records.find((r) => memoryStatus(r.item) === "active");
+      records = records.filter(
+        (r) => memoryStatus(r.item) !== "active" || r === firstActive
+      );
+    }
+    return records;
+  }
+  async search(query, opts = {}) {
+    const limit = opts.limit ?? DEFAULT_SEARCH_LIMIT;
+    const candidates = await this.list(opts.filter);
+    const byId = new Map(candidates.map((r) => [r.item.id, r]));
+    const hits = /* @__PURE__ */ new Map();
+    const terms = query.toLowerCase().split(/\s+/).filter(Boolean);
+    for (const record of candidates) {
+      const hit = keywordHit(record, terms);
+      if (hit) hits.set(record.item.id, hit);
+    }
+    const foreign = [];
+    if (this.#knowledge && !opts.filter?.scope) {
+      const result = await this.#knowledge.query({ query, topK: limit });
+      for (const kh of result.hits) {
+        const named = kh.metadata?.memoryId;
+        const memoryId = typeof named === "string" ? named : kh.sourceId;
+        const record = byId.get(memoryId);
+        if (record) {
+          const prior = hits.get(memoryId);
+          if (prior) prior.score = Math.max(prior.score ?? 0, kh.score);
+          else hits.set(memoryId, memoryHit(record, kh.text || void 0, kh.score));
+          continue;
+        }
+        if (typeof named === "string" || await this.read(memoryId)) continue;
+        const title = kh.metadata?.title;
+        foreign.push(
+          compact({
+            source: "knowledge",
+            title: typeof title === "string" && title ? title : kh.sourceId,
+            snippet: kh.text ? clip(kh.text) : void 0,
+            score: kh.score,
+            ref: kh.chunkId ? `${kh.sourceId}#${kh.chunkId}` : kh.sourceId
+          })
+        );
+      }
+    }
+    return [...hits.values(), ...foreign].sort((a, b) => (b.score ?? 0) - (a.score ?? 0)).slice(0, limit);
+  }
+  supersede(oldId, next, opts = {}) {
+    return this.#exclusive(async () => {
+      const old = await this.#mustFind(oldId, opts.scope);
+      checkRevision(oldId, opts.ifRevision, old.record.revision);
+      const from = memoryStatus(old.record.item);
+      if (from !== "active") throw new MemoryTransitionError(oldId, from, "superseded");
+      if (next.id === oldId) {
+        throw invalid("id", "the next item must have a new id (rule 20)");
+      }
+      const committed = await this.#commit(
+        next,
+        { mode: "commit", ...opts.scope ? { scope: opts.scope } : {} },
+        oldId,
+        old.record.item
+      );
+      const retired = await this.#rewriteStatus(old, "superseded");
+      return { old: retired, next: committed };
+    });
+  }
+  archive(id, opts = {}) {
+    return this.#exclusive(async () => {
+      const stored = await this.#mustFind(id, opts.scope);
+      checkRevision(id, opts.ifRevision, stored.record.revision);
+      const from = memoryStatus(stored.record.item);
+      if (from === "archived") return stored.record;
+      if (from !== "active") throw new MemoryTransitionError(id, from, "archived");
+      return this.#rewriteStatus(stored, "archived");
+    });
+  }
+  dismiss(proposalId, opts = {}) {
+    return this.#exclusive(async () => {
+      if (!PROPOSAL_ID.test(proposalId)) throw new MemoryNotFoundError("proposal", proposalId);
+      if (opts.scope && !await this.#proposalVisible(proposalId, opts.scope)) {
+        throw new MemoryNotFoundError("proposal", proposalId);
+      }
+      try {
+        await unlink(this.#proposalPath(proposalId));
+      } catch (err) {
+        if (isNotFound(err)) throw new MemoryNotFoundError("proposal", proposalId);
+        throw err;
+      }
+    });
+  }
+  async #propose(item, opts) {
+    const doc = clean(
+      applyWriteScope(item, opts.scope, {
+        ...opts.owner ? { owner: opts.owner } : {},
+        declaresTrees: this.#declaresTrees
+      })
+    );
+    const result = validateMemory(doc);
+    if (!result.ok) {
+      throw new MemoryValidationError("FilesMemoryStore.write (AIP-72 rule 13)", result.errors);
+    }
+    const text = renderMemory(doc);
+    const proposalId = sha256(text);
+    const path = this.#proposalPath(proposalId);
+    const existing = await readText(path);
+    if (existing === null) await atomicWrite(path, text);
+    return { item: parseMemory(text), revision: proposalId, proposalId };
+  }
+  /**
+   * The commit half of `write`, unlocked. `ignoreSlugOf` is the item being
+   * superseded, `superseded` its document: the new item inherits its node
+   * and ownership when it names none.
+   */
+  async #commit(item, opts, ignoreSlugOf, superseded) {
+    let doc = clean(item);
+    if (opts.fromProposal !== void 0) {
+      const known = PROPOSAL_ID.test(opts.fromProposal) && await readText(this.#proposalPath(opts.fromProposal)) !== null && (!opts.scope || await this.#proposalVisible(opts.fromProposal, opts.scope));
+      if (!known) throw new MemoryNotFoundError("proposal", opts.fromProposal);
+    }
+    if (doc.id !== void 0 && !SAFE_ID.test(doc.id)) {
+      throw invalid("id", "must be a file stem: [A-Za-z0-9] then [A-Za-z0-9_.-]");
+    }
+    const existing = doc.id === void 0 ? null : await this.#find(doc.id);
+    if (existing && !visible(existing.record, opts.scope)) {
+      throw new MemoryNotFoundError("item", doc.id);
+    }
+    doc = clean(
+      applyWriteScope(doc, opts.scope, {
+        ...opts.owner ? { owner: opts.owner } : {},
+        ...existing || superseded ? { basis: existing?.record.item ?? superseded } : {},
+        declaresTrees: this.#declaresTrees && !existing
+      })
+    );
+    const replaced = existing?.record.item ?? superseded;
+    if (replaced && opts.scope) assertRetagOnly(replaced, doc);
+    const now = this.#now().toISOString();
+    let next;
+    if (!existing) {
+      if (opts.ifRevision !== void 0) {
+        throw new MemoryConflictError(doc.id ?? "(new item)", opts.ifRevision, void 0);
+      }
+      const status = memoryStatus(doc);
+      if (status !== "active") {
+        throw new MemoryTransitionError(
+          doc.id ?? "(new item)",
+          "active",
+          status,
+          "a writer creates an item active (section 3)"
+        );
+      }
+      next = { ...doc, id: doc.id ?? await this.#newId(), updated_at: now };
+      if (next.written !== void 0) next.written = now;
+      assertValid(next, true);
+    } else {
+      const current = existing.record;
+      const id2 = doc.id;
+      if (sameContent(current.item, doc)) {
+        await this.#dropProposal(opts.fromProposal);
+        return current;
+      }
+      checkRevision(id2, opts.ifRevision, current.revision);
+      const from = memoryStatus(current.item);
+      const to = memoryStatus(doc);
+      if (from !== to) {
+        throw new MemoryTransitionError(
+          id2,
+          from,
+          to,
+          from === "active" ? "retire an item through supersede or archive" : void 0
+        );
+      }
+      next = { ...doc, updated_at: now };
+      if (next.written !== void 0 || current.item.written !== void 0) next.written = now;
+      assertValid(next, false);
+    }
+    const id = next.id;
+    await this.#assertSlugFree(next, ignoreSlugOf);
+    const path = this.#itemPath(itemType(next), id);
+    if (existing && existing.path !== path) {
+      await mkdir(join(path, ".."), { recursive: true });
+      await rename(existing.path, path);
+    }
+    const text = renderMemory(next);
+    await atomicWrite(path, text);
+    await this.#dropProposal(opts.fromProposal);
+    return { item: withId(parseMemory(text), id), revision: sha256(text) };
+  }
+  /**
+   * Supersede and archive are status-only rewrites (rules 6 and 19): the
+   * `status` line is replaced, or added before the closing fence, and
+   * every other byte stays as it was, whoever wrote the file.
+   */
+  async #rewriteStatus(stored, status) {
+    const text = setStatusLine(stored.text, status);
+    const item = withId(parseMemory(text), stored.record.item.id);
+    if (item.status !== status) {
+      throw new Error(`memory store (AIP-72): could not rewrite the status of '${item.id}'`);
+    }
+    await atomicWrite(stored.path, text);
+    return { item, revision: sha256(text) };
+  }
+  async #assertSlugFree(next, ignore) {
+    if (next.slug === void 0 || memoryStatus(next) !== "active") return;
+    for (const { record } of await this.#allItems()) {
+      const other = record.item;
+      if (other.id === next.id || other.id === ignore) continue;
+      if (other.slug === next.slug && memoryStatus(other) === "active") {
+        throw new MemorySlugTakenError(next.slug, other.id);
+      }
+    }
+  }
+  async #dropProposal(proposalId) {
+    if (proposalId === void 0) return;
+    try {
+      await unlink(this.#proposalPath(proposalId));
+    } catch (err) {
+      if (!isNotFound(err)) throw err;
+    }
+  }
+  async #newId() {
+    for (; ; ) {
+      const id = `mem_${Array.from(randomBytes(8), (b) => ID_ALPHABET[b % 36]).join("")}`;
+      if (!await this.#find(id)) return id;
+    }
+  }
+  async #mustFind(id, scope) {
+    const stored = await this.#find(id);
+    if (!stored || !visible(stored.record, scope)) throw new MemoryNotFoundError("item", id);
+    return stored;
+  }
+  async #proposalVisible(proposalId, scope) {
+    const text = await readText(this.#proposalPath(proposalId));
+    return text !== null && isInNodeProjection(parseMemory(text), scope);
+  }
+  async #find(id) {
+    if (!SAFE_ID.test(id)) return null;
+    for (const dir of await listDir(join(this.#root, "items"))) {
+      const path = join(this.#root, "items", dir, `${id}.md`);
+      const text = await readText(path);
+      if (text !== null) return { record: itemRecord(text, id), path, text };
+    }
+    return null;
+  }
+  async #allItems() {
+    const out = [];
+    for (const dir of await listDir(join(this.#root, "items"))) {
+      for (const file of await listDir(join(this.#root, "items", dir))) {
+        if (!isMarkdown(file)) continue;
+        const path = join(this.#root, "items", dir, file);
+        const text = await readText(path);
+        if (text !== null) out.push({ record: itemRecord(text, file.slice(0, -3)), path, text });
+      }
+    }
+    return out;
+  }
+  async #allProposals() {
+    const out = [];
+    for (const file of await listDir(join(this.#root, "proposals"))) {
+      if (!isMarkdown(file)) continue;
+      const path = join(this.#root, "proposals", file);
+      const text = await readText(path);
+      if (text === null) continue;
+      const proposalId = file.slice(0, -3);
+      out.push({ record: { item: parseMemory(text), revision: sha256(text), proposalId }, path, text });
+    }
+    return out;
+  }
+  #itemPath(type, id) {
+    return join(this.#root, "items", type, `${id}.md`);
+  }
+  #proposalPath(proposalId) {
+    return join(this.#root, "proposals", `${proposalId}.md`);
+  }
+  #exclusive(fn) {
+    const run = this.#tail.then(fn);
+    this.#tail = run.catch(() => void 0);
+    return run;
+  }
+};
+function visible(record, scope) {
+  return scope === void 0 || isInNodeProjection(record.item, scope);
+}
+function itemRecord(text, id) {
+  return { item: withId(parseMemory(text), id), revision: sha256(text) };
+}
+function withId(item, id) {
+  return item.id === void 0 ? { ...item, id } : item;
+}
+function itemType(item) {
+  return item.type ?? item.kind;
+}
+function assertValid(doc, creating) {
+  const result = validateMemory(doc, { canonical: creating });
+  if (!result.ok) {
+    throw new MemoryValidationError("FilesMemoryStore.write (AIP-72 rule 13)", result.errors);
+  }
+}
+function invalid(path, message) {
+  const issue = { path, message, rule: "rule-13" };
+  return new MemoryValidationError("FilesMemoryStore (AIP-72)", [issue]);
+}
+function checkRevision(id, given, actual) {
+  if (given !== actual) throw new MemoryConflictError(id, given, actual);
+}
+function sameContent(a, b) {
+  const strip = (d) => {
+    const { updated_at: _u, written: _w, ...rest } = d;
+    return stableJson({ ...rest, status: memoryStatus(d) });
+  };
+  return strip(a) === strip(b);
+}
+function stableJson(value) {
+  return JSON.stringify(
+    value,
+    (_key, v) => v && typeof v === "object" && !Array.isArray(v) ? Object.fromEntries(Object.entries(v).sort(([x], [y]) => x < y ? -1 : x > y ? 1 : 0)) : v
+  );
+}
+function clean(item) {
+  return JSON.parse(JSON.stringify(item));
+}
+function setStatusLine(text, status) {
+  const lines = text.split("\n");
+  const open = lines[0]?.replace(/^/, "").trimEnd();
+  const close = lines.findIndex((l, i) => i > 0 && l.trimEnd() === "---");
+  if (open !== "---" || close < 0) {
+    throw new Error("memory store (AIP-72): item file has no frontmatter fence");
+  }
+  const cr = lines[close].endsWith("\r") ? "\r" : "";
+  const line = `status: "${status}"`;
+  const at = lines.findIndex((l, i) => i > 0 && i < close && /^status[ \t]*:/.test(l));
+  if (at >= 0) lines[at] = line + (lines[at].endsWith("\r") ? "\r" : "");
+  else lines.splice(close, 0, line + cr);
+  return lines.join("\n");
+}
+function keywordHit(record, terms) {
+  if (terms.length === 0) return null;
+  const { item } = record;
+  const title = [item.title, item.name, item.slug].filter(Boolean).join(" ").toLowerCase();
+  const description = (item.description ?? "").toLowerCase();
+  const body = item.body.toLowerCase();
+  let points = 0;
+  for (const term of terms) {
+    if (title.includes(term)) points += 3;
+    if (description.includes(term)) points += 2;
+    if (body.includes(term)) points += 1;
+  }
+  if (points === 0) return null;
+  const snippetFrom = [item.body, item.description ?? ""].find(
+    (t) => terms.some((term) => t.toLowerCase().includes(term))
+  );
+  const snippet = snippetFrom ? around(snippetFrom, terms) : void 0;
+  return memoryHit(record, snippet, points / (6 * terms.length));
+}
+function memoryHit(record, snippet, score) {
+  const { item } = record;
+  return compact({
+    source: "memory",
+    id: item.id,
+    slug: item.slug,
+    title: item.title ?? item.name ?? item.id,
+    snippet: snippet ?? (item.description || clip(item.body) || void 0),
+    score
+  });
+}
+function around(text, terms) {
+  const lower = text.toLowerCase();
+  const at = Math.min(
+    ...terms.map((t) => lower.indexOf(t)).filter((i) => i >= 0)
+  );
+  const start = Math.max(0, at - SNIPPET_CHARS / 4);
+  return clip(text.slice(start));
+}
+function clip(text) {
+  const flat = text.replace(/\s+/g, " ").trim();
+  return flat.length > SNIPPET_CHARS ? `${flat.slice(0, SNIPPET_CHARS - 1)}\u2026` : flat;
+}
+function compact(value) {
+  return Object.fromEntries(Object.entries(value).filter(([, v]) => v !== void 0));
+}
+function byNewest(a, b) {
+  const ta = a.item.updated_at ?? a.item.written ?? "";
+  const tb = b.item.updated_at ?? b.item.written ?? "";
+  if (ta !== tb) return ta < tb ? 1 : -1;
+  const ia = a.proposalId ?? a.item.id ?? "";
+  const ib = b.proposalId ?? b.item.id ?? "";
+  return ia < ib ? -1 : ia > ib ? 1 : 0;
+}
+function toArray(value) {
+  if (value === void 0) return void 0;
+  return Array.isArray(value) ? value : [value];
+}
+function isMarkdown(file) {
+  return file.endsWith(".md") && !file.startsWith(".");
+}
+function sha256(text) {
+  return createHash("sha256").update(text).digest("hex");
+}
+async function atomicWrite(path, text) {
+  const dir = join(path, "..");
+  await mkdir(dir, { recursive: true });
+  const tmp = join(dir, `.${randomBytes(6).toString("hex")}.tmp`);
+  await writeFile(tmp, text, "utf8");
+  try {
+    await rename(tmp, path);
+  } catch (err) {
+    await unlink(tmp).catch(() => void 0);
+    throw err;
+  }
+}
+async function readText(path) {
+  try {
+    return await readFile(path, "utf8");
+  } catch (err) {
+    if (isNotFound(err)) return null;
+    throw err;
+  }
+}
+async function listDir(path) {
+  try {
+    return (await readdir(path)).sort();
+  } catch (err) {
+    if (isNotFound(err)) return [];
+    throw err;
+  }
+}
+function isNotFound(err) {
+  const code = err?.code;
+  return code === "ENOENT" || code === "ENOTDIR";
+}
+
 // src/index.ts
 var SPEC_NAME = "memory/v1";
 var SPEC_VERSION = "1.0.0-alpha";
 
-export { MEMORY_STATUSES, MEMORY_TYPES, MemoryParseError, MemoryValidationError, SPEC_NAME, SPEC_VERSION, defineMemory, isAllowedStatusTransition, isInForce, memoryFrontmatterSchema, memoryStatus, parseMemory, renderMemory, validateMemory };
+export { FilesMemoryStore, MEMORY_STATUSES, MEMORY_TYPES, MemoryConflictError, MemoryNotFoundError, MemoryParseError, MemorySlugTakenError, MemoryStoreError, MemoryTransitionError, MemoryValidationError, SPEC_NAME, SPEC_VERSION, applyWriteScope, assertRetagOnly, defineMemory, isAllowedStatusTransition, isInForce, isInNodeProjection, isNodeOrOperatorTag, memoryFrontmatterSchema, memoryStatus, nodeAnchorIds, nodeTag, operatorAnchorIds, operatorTag, parseMemory, renderMemory, validateMemory };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map