@agentproto/memory 0.0.0 → 0.1.0

package/README.md

@@ -7,7 +7,8 @@ lifecycle (`active`, then `superseded` or `archived`), stored as markdown
 with YAML frontmatter.
 
 Spec: <https://agentproto.sh/docs/aip-72>. This package covers the
-document only; a store port and per-harness projection come later.
+document (sections 1 to 7) and the store (section 8); the per-harness
+projection (section 9) lives with the hosts.
 
 ## Usage
 
@@ -45,6 +46,80 @@ const { ok, errors, warnings } = validateMemory(doc)
 active) and an absent `body` as `""`. Lifecycle helpers: `memoryStatus`,
 `isAllowedStatusTransition`, `isInForce`.
 
+## Store
+
+`MemoryStore` (alias `IMemoryStore`) is the section 8 port: `write`
+(`propose` or `commit`), `read`, `list`, `search`, `supersede`, `archive`,
+`dismiss`. `FilesMemoryStore` implements it over the reference layout:
+
+```
+<root>/items/<type>/<id>.md      one memory/v1 item per file
+<root>/proposals/<sha256>.md     pending proposals, not items
+```
+
+```ts
+import { FilesMemoryStore } from "@agentproto/memory"
+
+const store = new FilesMemoryStore({ root: ".agentproto/memory" })
+const rec = await store.write(item, { mode: "commit" }) // assigns an id
+await store.archive(rec.item.id!, { ifRevision: rec.revision })
+const hits = await store.search("pnpm") // in-force items by default
+```
+
+- `revision` is the SHA-256 of the file bytes. A commit that changes an
+  item, `supersede` and `archive` need the current `ifRevision`, else they
+  reject with `MemoryConflictError`; an equal re-write is a no-op.
+- `supersede` and `archive` rewrite the `status` line only; no item file
+  is ever deleted. Other failures: `MemoryNotFoundError`,
+  `MemoryTransitionError` (e.g. `superseded` to `active`),
+  `MemorySlugTakenError`, and `MemoryValidationError` naming the field.
+- `search` matches title, description and body. Pass `knowledge` (any
+  AIP-10 `IKnowledgeProvider`, typed structurally so this package does not
+  depend on the knowledge engine) to merge its hits: a hit naming an item
+  of the store (`metadata.memoryId` or its `sourceId`) is checked against
+  the files, anything else comes back as `source: "knowledge"`.
+
+## Daemon tools and spawn digest
+
+The agentproto daemon (`@agentproto/runtime`) serves a `FilesMemoryStore`
+as MCP tools: `memory_search`, `memory_list`, `memory_read` and
+`memory_write` (default mode `propose`) for every caller, and a `commit`
+mode plus `memory_supersede`, `memory_archive` and `memory_dismiss` for the
+operator or a supervisor session only. Its default root is
+`~/.agentproto/memory` (daemon config `memory.root`). An agent whose
+AGENT.md binds memory (`memory.enabled: true`, `store` or `anchors`) also
+gets the section 9 digest of its in-force, in-scope items appended to its
+system prompt at spawn. See the runtime README's MCP tool surface.
+
+## Native memory (claude-code)
+
+An adapter declaring `capabilities.memory { inject: "native-dir", capture:
+"native-dir-diff" }` (claude-code) gets the same in-force items written into
+its own memory dir instead of the system prompt:
+
+- The dir is `<session config dir>/memory`, pinned through
+  `autoMemoryDirectory` in the session's isolated `settings.json`
+  (`~/.agentproto/adapter-config/<lineage>/memory`). The user's real
+  `~/.claude` is never written.
+- One topic file per item, `agentproto_<slug>.md`, with the native
+  frontmatter plus `metadata.agentprotoId`, `agentprotoSlug` and
+  `agentprotoSha`. The index lines live in one fenced block at the top of
+  `MEMORY.md` (`<!-- agentproto:begin -->` ... `<!-- agentproto:end -->`),
+  bounded well under the CLI's 200 lines / 25KB cut and ending with the
+  number of items left out. Lines and files the agent wrote are not
+  touched; every spawn rewrites only the block and the `agentproto_*` files.
+- Fallback: when auto memory is off (`CLAUDE_CODE_DISABLE_AUTO_MEMORY=1`, a
+  repo `.claude/settings*.json` with `autoMemoryEnabled: false`) or the repo
+  pins its own `autoMemoryDirectory`, nothing is projected and the digest
+  rides the system prompt. Never both.
+- Capture: at each turn end and at exit the daemon diffs the dir against
+  the spawn snapshot (`.agentproto-memory.json`) and writes every new or
+  changed native file to the agent's store as a proposal (`memory/v1`,
+  `provenance.source: native-memory`, `capture.mode: live`). An edited
+  projected file is a proposal on the same `id`, a deleted one a proposal
+  with `status: archived`. Nothing is committed; a file is proposed once
+  per content. Sandbox sessions are not captured yet.
+
 ## License
 
 Apache-2.0. See [LICENSE](./LICENSE).

package/dist/index.d.ts

@@ -16,10 +16,14 @@ declare const MEMORY_STATUSES: readonly ["active", "superseded", "archived"];
 /** Lifecycle status. Absent means `active` (AIP-72 rule 9). */
 type MemoryStatus = (typeof MEMORY_STATUSES)[number];
 interface MemoryAnchor {
-    kind: "global" | "project" | "task" | "session" | "pr" | "contact" | "agent";
+    kind: "global" | "project" | "task" | "session" | "pr" | "contact" | "agent" | "node" | "operator";
     /** Anchor target slug (project, contact, agent). */
     slug?: string;
-    /** Anchor target id (task, session). */
+    /**
+     * Anchor target id (task, session, node, operator). A node's is its
+     * AIP-34 id (`@<owner>/<slug>`), an operator's the body of its AIP-54
+     * `operator:` ref (`<slug>` or `<slug>@<workspace>`). Section 10.
+     */
     id?: string;
     /** Repository `owner/name` for a pr anchor. */
     repo?: string;
@@ -155,6 +159,14 @@ interface ValidateMemoryOptions {
  * section 2 (`kind` set), rules 1, 2, 4 and 5 as errors, rule 8 as
  * warnings. Rules 6 and 7 compare two versions of an item and belong to
  * the store; `isAllowedStatusTransition` covers rule 7's table.
+ *
+ * Defaults: MEMORY.schema.json gives `tags` (and `evidence.anchorsResolved`,
+ * `evidence.flags`) `default: []`, and the generated zod carries it. This
+ * function only checks: it never returns the parsed data, so the default
+ * is never filled in. An item without `tags` stays without `tags` and
+ * reads as untagged (the digest treats it as `global`, AIP-72 section 9).
+ * An explicit `tags: []` validates: rule 4 rejects empty strings and empty
+ * objects, not empty arrays, though a writer omits it (`defineMemory`).
  */
 declare function validateMemory(doc: unknown, opts?: ValidateMemoryOptions): MemoryValidationResult;
 
@@ -176,9 +188,13 @@ declare function parseMemory(markdown: string): MemoryDocument;
  *
  * Every string value is double-quoted, so a YAML 1.1 or 1.2 reader
  * reads it back as a string (rule 3); undefined fields are omitted
- * (rule 4); key order is the document's own, so a status-only rewrite
- * changes only the `status` line (rule 6). `parseMemory(renderMemory(d))`
- * deep-equals `d`.
+ * (rule 4); key order is the document's own. So re-rendering a file this
+ * function wrote, with only `status` changed, changes only the `status`
+ * line (rule 6). That does not hold for a file another writer produced
+ * (unquoted strings, other key styles, comments): re-rendering it
+ * normalizes every line, which is why the store rewrites the status line
+ * in place instead (`setStatusLine`, `files-store.ts`).
+ * `parseMemory(renderMemory(d))` deep-equals `d`.
  */
 declare function renderMemory(doc: MemoryDocument): string;
 
@@ -273,6 +289,8 @@ declare const memoryFrontmatterSchema: z.ZodIntersection<z.ZodObject<{
                 pr: "pr";
                 contact: "contact";
                 agent: "agent";
+                node: "node";
+                operator: "operator";
             }>;
             slug: z.ZodOptional<z.ZodString>;
             id: z.ZodOptional<z.ZodString>;
@@ -323,6 +341,8 @@ declare const memoryFrontmatterSchema: z.ZodIntersection<z.ZodObject<{
                     pr: "pr";
                     contact: "contact";
                     agent: "agent";
+                    node: "node";
+                    operator: "operator";
                 }>;
                 slug: z.ZodOptional<z.ZodString>;
                 id: z.ZodOptional<z.ZodString>;
@@ -345,6 +365,292 @@ declare const memoryFrontmatterSchema: z.ZodIntersection<z.ZodObject<{
     body: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>, z.ZodUnion<readonly [z.ZodAny, z.ZodAny]>>;
 
+/**
+ * AIP-72 section 8: the memory store port.
+ *
+ * The shapes below are the ones section 8 fixes, name for name. A store
+ * keys items by `id`; `slug`, when present, is a second handle that is
+ * unique among active items (rule 14). Writes are compare-and-set on the
+ * opaque `revision` (rule 17), and nothing is ever hard deleted (rule 16).
+ */
+/** One stored item, or one pending proposal. */
+interface MemoryRecord {
+    item: MemoryDocument;
+    /** Opaque; changes on every byte change of the stored document. */
+    revision: string;
+    /** Set on a proposal, absent on an item. */
+    proposalId?: string;
+}
+/**
+ * AIP-72 section 10. Built by the host from the calling session, never by
+ * the store, and handed in on every operation made on a session's behalf.
+ * A call with no `scope` is a host call (rule 30).
+ */
+interface MemoryScope {
+    /**
+     * The node projection: AIP-34 node ids, nearest first, already cut at a
+     * sealed or hard node. Empty: the session has no node scope.
+     */
+    readonly nodes: readonly string[];
+    /** Id of the root node of the session's tree. */
+    readonly tree?: string;
+    /** The operator anchor id, when the session runs an operator. */
+    readonly operator?: string;
+}
+interface MemoryFilter {
+    type?: MemoryType | readonly MemoryType[];
+    status?: MemoryStatus | readonly MemoryStatus[];
+    /** Matches at most one active item (rule 14, rule 20 overlap). */
+    slug?: string;
+    /** Match any, e.g. `["global", "project:acme"]`. */
+    tags?: readonly string[];
+    /** Rules 10 and 11, at the store's clock. */
+    inForce?: boolean;
+    /** List proposals instead of items. */
+    proposals?: boolean;
+    /** Section 10: only the items in the scope's node projection. Absent: a host call. */
+    scope?: MemoryScope;
+}
+interface MemorySearchHit {
+    source: "memory" | "knowledge";
+    /** REQUIRED when `source` is `"memory"`. */
+    id?: string;
+    slug?: string;
+    title: string;
+    snippet?: string;
+    score?: number;
+    /** Provider pointer when `source` is `"knowledge"`. */
+    ref?: string;
+}
+interface MemoryWriteOptions {
+    mode: "propose" | "commit";
+    /** The revision the caller last read (rule 17). */
+    ifRevision?: string;
+    /** The proposal this commit promotes; dropped once the item is written (rule 21). */
+    fromProposal?: string;
+    /** Section 10: the calling session's scope. Absent: a host call. */
+    scope?: MemoryScope;
+    /**
+     * Rule 32, on a create. `"operator"` (the default) owns the item by the
+     * session's operator; `"node"` shares it with every operator of the node.
+     */
+    owner?: "operator" | "node";
+}
+interface MemorySearchOptions {
+    filter?: MemoryFilter;
+    limit?: number;
+}
+interface MemoryStore {
+    write(item: MemoryDocument, opts: MemoryWriteOptions): Promise<MemoryRecord>;
+    read(id: string, opts?: {
+        scope?: MemoryScope;
+    }): Promise<MemoryRecord | null>;
+    list(filter?: MemoryFilter): Promise<readonly MemoryRecord[]>;
+    search(query: string, opts?: MemorySearchOptions): 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>;
+}
+/** The section 8 port under the `I*` name its knowledge sibling uses. */
+type IMemoryStore = MemoryStore;
+type MemoryStoreErrorCode = "conflict" | "not-found" | "invalid-transition" | "slug-taken";
+/**
+ * Base of the store's typed failures. An invalid document is rejected
+ * with the document package's `MemoryValidationError` instead, which
+ * names the field (rule 13).
+ */
+declare class MemoryStoreError extends Error {
+    readonly code: MemoryStoreErrorCode;
+    constructor(code: MemoryStoreErrorCode, message: string);
+}
+/** Rule 17: `ifRevision` missing or stale on a write that needs it. */
+declare class MemoryConflictError extends MemoryStoreError {
+    readonly id: string;
+    /** The revision the caller sent, if any. */
+    readonly expected: string | undefined;
+    /** The revision on disk, `undefined` when the item does not exist. */
+    readonly actual: string | undefined;
+    constructor(id: string, expected: string | undefined, actual: string | undefined);
+}
+/** No item (or proposal) with that id. */
+declare class MemoryNotFoundError extends MemoryStoreError {
+    readonly id: string;
+    readonly what: "item" | "proposal";
+    constructor(what: "item" | "proposal", id: string);
+}
+/** Rules 7 and 15: a status move the store does not allow. */
+declare class MemoryTransitionError extends MemoryStoreError {
+    readonly id: string;
+    readonly from: MemoryStatus;
+    readonly to: MemoryStatus;
+    constructor(id: string, from: MemoryStatus, to: MemoryStatus, detail?: string);
+}
+/** Rule 14: another active item already holds the slug. */
+declare class MemorySlugTakenError extends MemoryStoreError {
+    readonly slug: string;
+    /** The active item holding it. */
+    readonly holder: string;
+    constructor(slug: string, holder: string);
+}
+
+type Tagged = Pick<MemoryFrontmatter, "tags">;
+/** `node:<id>`, `id` being the AIP-34 id of a node (`@<owner>/<slug>`). */
+declare function nodeTag(id: string): string;
+/** `operator:<id>`, `id` being the body of an AIP-54 `operator:` ref. */
+declare function operatorTag(id: string): string;
+/** The ids of the item's node anchors (an item carries at most one). */
+declare function nodeAnchorIds(item: Tagged): string[];
+/** The ids of the item's operator anchors (an item carries at most one). */
+declare function operatorAnchorIds(item: Tagged): string[];
+/** Whether a tag is a node or operator anchor (neither counts as an anchor for section 9). */
+declare function isNodeOrOperatorTag(tag: string): boolean;
+interface NodeProjectionOptions {
+    /**
+     * Operator anchor ids the store's AIP-38 read grants let the session
+     * read (condition 4). A grant never extends condition 2.
+     */
+    grantedOperators?: Iterable<string>;
+}
+/**
+ * Conditions 2 and 4 of the node projection (section 10), the two that
+ * read an item's node and operator anchors. Conditions 1 (in force) and 3
+ * (the session's flat anchors) stay with the caller, which has the clock
+ * and the anchors; the conditions are an intersection.
+ *
+ * - With a node scope the item must carry a node anchor, and every node
+ *   anchor it carries must be in `scope.nodes`; an item with none is out.
+ * - Without one, an item with a node anchor is out and one with none is
+ *   judged by the other conditions alone.
+ * - An operator anchor needs the session to run that operator, or a grant.
+ */
+declare function isInNodeProjection(item: Tagged, scope: MemoryScope, opts?: NodeProjectionOptions): boolean;
+interface WriteScopeOptions {
+    /** Rule 32. Default `"operator"`; `"node"` adds no operator anchor. */
+    owner?: "operator" | "node";
+    /**
+     * The item this write replaces or supersedes. A document that names no
+     * node anchor keeps the basis's, and a document that names no owner keeps
+     * the basis's kind of ownership, so an edit never moves or hands over an
+     * item by default (rule 34: nothing promotes an item by itself).
+     */
+    basis?: Tagged;
+    /** Rule 33: the host declares trees, so a document with no node anchor is refused. */
+    declaresTrees?: boolean;
+}
+/**
+ * The document a write stores: the node and operator anchors added by
+ * default (rules 31 to 33), or a validation error naming `tags`. `scope`
+ * absent is a host call (rule 30): nothing is added or confined, but a
+ * store whose host declares trees still refuses a document with no node
+ * anchor (rule 33).
+ */
+declare function applyWriteScope(item: MemoryDocument, scope: MemoryScope | undefined, opts?: WriteScopeOptions): MemoryDocument;
+/**
+ * Rule 34. A commit that moves an item to another node changes that anchor
+ * and nothing else: not the operator anchor, not the other anchors. (That
+ * the new node is in `scope.nodes` is `applyWriteScope`'s check; a node above
+ * a sealed or hard wall never is, the projection being cut there.)
+ */
+declare function assertRetagOnly(before: Tagged, after: Tagged): void;
+
+/**
+ * One hit of a knowledge provider, as much of the AIP-10
+ * `KnowledgeHit` as the store reads.
+ */
+interface MemoryKnowledgeHit {
+    readonly sourceId: string;
+    readonly chunkId?: string;
+    readonly text: string;
+    readonly score: number;
+    /** `memoryId` (string) names the memory item the hit was indexed from. */
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+/**
+ * The slice of an AIP-10 `IKnowledgeProvider` (`@agentproto/knowledge-engine`)
+ * the store delegates search to. Declared structurally so this package
+ * takes no dependency on the knowledge engine: any `IKnowledgeProvider`
+ * fits as is.
+ */
+interface MemoryKnowledgeProvider {
+    query(q: {
+        readonly query: string;
+        readonly topK?: number;
+    }): Promise<{
+        readonly hits: readonly MemoryKnowledgeHit[];
+    }>;
+}
+interface FilesMemoryStoreOptions {
+    /** The store directory: `items/<type>/<id>.md` and `proposals/<id>.md` below it. */
+    root: string;
+    /**
+     * Optional search delegate. Its hits are merged with the built-in
+     * keyword match: a hit naming an item of this store is checked against
+     * the files (rule 22), anything else comes back as `source: "knowledge"`.
+     */
+    knowledge?: MemoryKnowledgeProvider;
+    /** The store's clock: `updated_at` on commits, and the in-force check. */
+    now?: () => Date;
+    /**
+     * The host declares AIP-34 trees (section 10, rule 33): a host call that
+     * creates an item or a proposal with no node anchor is refused. Off: the
+     * store behaves as sections 8 and 9 alone.
+     */
+    declaresTrees?: boolean;
+}
+/**
+ * AIP-72 section 8 reference store over a directory:
+ *
+ * ```
+ * <root>/items/<type>/<id>.md      one memory/v1 item per file
+ * <root>/proposals/<sha256>.md     pending proposals, not items
+ * ```
+ *
+ * The files are the source of truth and the store keeps no index.
+ * `revision` is the SHA-256 (hex) of the file bytes, a proposal id the
+ * SHA-256 of the rendered proposal. Files are written to a temp file
+ * then renamed into place. Item files are never deleted: a type change
+ * renames the file, supersede and archive rewrite the `status` line
+ * only. Mutations through one instance are serialized, so a
+ * compare-and-set cannot interleave with another write of the same
+ * store object; several processes writing one directory are not
+ * coordinated.
+ */
+declare class FilesMemoryStore implements MemoryStore {
+    #private;
+    constructor(options: FilesMemoryStoreOptions);
+    write(item: MemoryDocument, opts: MemoryWriteOptions): Promise<MemoryRecord>;
+    read(id: string, opts?: {
+        scope?: MemoryScope;
+    }): Promise<MemoryRecord | null>;
+    list(filter?: MemoryFilter): Promise<readonly MemoryRecord[]>;
+    search(query: string, opts?: MemorySearchOptions): 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>;
+}
+
 /**
  * @agentproto/memory: AIP-72 memory/v1 reference implementation.
  *
@@ -358,8 +664,15 @@ declare const memoryFrontmatterSchema: z.ZodIntersection<z.ZodObject<{
  *   - TS:  `defineMemory({...})` -> frozen `MemoryHandle` (writer, canonical)
  *   - MD:  `parseMemory(src)` -> `MemoryDocument`, then `validateMemory(doc)`
  *   - out: `renderMemory(doc)` -> MEMORY.md text
+ *
+ * Store (section 8): the `MemoryStore` port and `FilesMemoryStore`, the
+ * reference layout (`items/<type>/<id>.md`, `proposals/<id>.md`).
+ *
+ * Node scope (section 10): `MemoryScope`, the `node:` and `operator:`
+ * anchors, and the projection and write rules over a scope the host
+ * computed (`isInNodeProjection`, `applyWriteScope`).
  */
 declare const SPEC_NAME: "memory/v1";
 declare const SPEC_VERSION: "1.0.0-alpha";
 
-export { MEMORY_STATUSES, MEMORY_TYPES, type MemoryAnchor, type MemoryCapture, type MemoryDecidedBy, type MemoryDefinition, type MemoryDocument, type MemoryEvidence, type MemoryFrontmatter, type MemoryHandle, type MemoryIssue, type MemoryLifetime, MemoryParseError, type MemoryProvenance, type MemoryStatus, type MemoryType, MemoryValidationError, type MemoryValidationResult, SPEC_NAME, SPEC_VERSION, type ValidateMemoryOptions, defineMemory, isAllowedStatusTransition, isInForce, memoryFrontmatterSchema, memoryStatus, parseMemory, renderMemory, validateMemory };
+export { FilesMemoryStore, type FilesMemoryStoreOptions, type IMemoryStore, MEMORY_STATUSES, MEMORY_TYPES, type MemoryAnchor, type MemoryCapture, MemoryConflictError, type MemoryDecidedBy, type MemoryDefinition, type MemoryDocument, type MemoryEvidence, type MemoryFilter, type MemoryFrontmatter, type MemoryHandle, type MemoryIssue, type MemoryKnowledgeHit, type MemoryKnowledgeProvider, type MemoryLifetime, MemoryNotFoundError, MemoryParseError, type MemoryProvenance, type MemoryRecord, type MemoryScope, type MemorySearchHit, type MemorySearchOptions, MemorySlugTakenError, type MemoryStatus, type MemoryStore, MemoryStoreError, type MemoryStoreErrorCode, MemoryTransitionError, type MemoryType, MemoryValidationError, type MemoryValidationResult, type MemoryWriteOptions, type NodeProjectionOptions, SPEC_NAME, SPEC_VERSION, type ValidateMemoryOptions, type WriteScopeOptions, applyWriteScope, assertRetagOnly, defineMemory, isAllowedStatusTransition, isInForce, isInNodeProjection, isNodeOrOperatorTag, memoryFrontmatterSchema, memoryStatus, nodeAnchorIds, nodeTag, operatorAnchorIds, operatorTag, parseMemory, renderMemory, validateMemory };