@agentproto/memory 0.0.0-stage → 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,678 @@
+import { z } from 'zod';
+
+/**
+ * AIP-72 memory/v1 document types.
+ *
+ * Hand-tuned on top of the shape `json-schema-to-typescript` generates
+ * from `resources/aip-72/draft/MEMORY.schema.json`: the `$defs` get
+ * `Memory*` names, and the document carries its markdown `body` as a
+ * required string (the schema's `body` property stands for the text
+ * after the closing frontmatter fence).
+ */
+declare const MEMORY_TYPES: readonly ["user", "feedback", "project", "reference"];
+/** The closed memory type set (`type`, and `kind` on a memory/v1 item). */
+type MemoryType = (typeof MEMORY_TYPES)[number];
+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" | "node" | "operator";
+    /** Anchor target slug (project, contact, agent). */
+    slug?: string;
+    /**
+     * 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;
+    /** Pull-request number for a pr anchor. */
+    number?: number;
+}
+interface MemoryLifetime {
+    kind: "durable" | "until" | "while" | "session";
+    /** Expiry timestamp, REQUIRED for kind `until`. */
+    at?: string;
+    /** Governing anchor, REQUIRED for kind `while`. */
+    anchor?: MemoryAnchor;
+}
+interface MemoryDecidedBy {
+    rule?: string;
+    source?: string;
+}
+interface MemoryProvenance {
+    source?: string;
+    /** Omitted, never empty, when the source has no session. */
+    sessionId?: string;
+    /** Omitted, never empty, when the source has none. */
+    ref?: string;
+    quote?: string;
+    at?: string;
+    extractorVersion?: string;
+}
+interface MemoryCapture {
+    mode?: "live" | "batch";
+    producer?: string;
+    capturedAt?: string;
+}
+interface MemoryEvidence {
+    sourceKind?: string;
+    trust?: string;
+    explicitness?: string;
+    corroborations?: number;
+    contradictsActive?: boolean;
+    impact?: string;
+    lifetime?: MemoryLifetime;
+    anchorsResolved?: string[];
+    ageHours?: number;
+    flags?: string[];
+}
+/**
+ * The YAML frontmatter of a memory/v1 item. Every field is optional at
+ * the type level: the schema accepts either the canonical AIP-10 base
+ * fields (`schema`, `slug`, `kind`, `title`, `updated_at`) or the legacy
+ * trio (`id`, `name`, `type`), which `validateMemory` checks.
+ */
+interface MemoryFrontmatter {
+    schema?: "memory/v1";
+    slug?: string;
+    kind?: string;
+    title?: string;
+    updated_at?: string;
+    id?: string;
+    name?: string;
+    type?: MemoryType;
+    description?: string;
+    tags?: string[];
+    polarity?: "do" | "dont";
+    lifetime?: MemoryLifetime;
+    status?: MemoryStatus;
+    created?: string;
+    written?: string;
+    decidedBy?: MemoryDecidedBy;
+    provenance?: MemoryProvenance;
+    evidence?: MemoryEvidence;
+    capture?: MemoryCapture;
+}
+/** One memory/v1 item: frontmatter fields plus the markdown body. */
+interface MemoryDocument extends MemoryFrontmatter {
+    body: string;
+}
+/** `defineMemory` input: `body` may be omitted for an item with no prose. */
+type MemoryDefinition = MemoryFrontmatter & {
+    body?: string;
+};
+/** The frozen item `defineMemory` returns, with `status` made explicit. */
+type MemoryHandle = Readonly<MemoryDocument & {
+    status: MemoryStatus;
+}>;
+/**
+ * One validation finding. `path` is the dot path of the offending field
+ * (`provenance.sessionId`, `lifetime.at`, `tags.0`), `""` for the whole
+ * document. `rule` is `schema` for a MEMORY.schema.json constraint,
+ * `section-2` for the memory/v1 `kind` set, or `rule-<n>` for AIP-72
+ * conformance rule n.
+ */
+interface MemoryIssue {
+    path: string;
+    message: string;
+    rule: string;
+}
+interface MemoryValidationResult {
+    ok: boolean;
+    errors: MemoryIssue[];
+    /** SHOULD-level findings (rule 8). Never make `ok` false. */
+    warnings: MemoryIssue[];
+}
+
+/**
+ * AIP-72 reference implementation of `defineMemory`: the writer path.
+ *
+ * Validates in canonical mode (rule 1: a writer sets `schema`, `slug`,
+ * `kind`, `title`, `updated_at` on every item it creates) and throws a
+ * `MemoryValidationError` whose `field` / `issues` name the offending
+ * field paths. Only two values are filled in: `status` becomes `active`
+ * when absent (section 3: a writer creates an item `active`), and an
+ * absent `body` becomes `""`. Nothing else is defaulted; in particular
+ * `tags` is not set to `[]`, since rule 4 omits an empty optional field.
+ *
+ * Built on `createDoctype` for the shared slug check and top-level
+ * freeze; the handle is frozen deeply and does not alias the input.
+ */
+declare function defineMemory(input: MemoryDefinition): MemoryHandle;
+
+interface ValidateMemoryOptions {
+    /**
+     * Require the canonical fields (`schema`, `slug`, `kind`, `title`,
+     * `updated_at`), as rule 1 asks of a writer creating an item. Off by
+     * default: a reader MUST accept legacy items (rule 9).
+     */
+    canonical?: boolean;
+}
+/**
+ * Validate one memory/v1 document (frontmatter fields plus `body`).
+ *
+ * Runs MEMORY.schema.json (through the generated zod, plus the
+ * `anyOf` and lifetime `if/then` branches the codegen cannot express)
+ * and the AIP-72 conformance rules checkable on a single document:
+ * 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;
+
+/**
+ * Split a MEMORY.md file into its frontmatter fields and `body`.
+ *
+ * The frontmatter is read as YAML 1.2 core schema, so a date-time stays
+ * a string and an unquoted `true`, `null` or `2026` in a string field
+ * reaches `validateMemory` as a non-string and fails there (rule 3).
+ * This only parses: it does not validate, so a reader can still load an
+ * item it will then inspect. The body is free (rule 12): one blank line
+ * after the closing fence is the separator, everything after it is kept
+ * byte for byte.
+ */
+declare function parseMemory(markdown: string): MemoryDocument;
+/**
+ * Render a memory/v1 document as MEMORY.md. Throws a
+ * `MemoryValidationError` if the document does not validate.
+ *
+ * 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 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;
+
+/** The item's status, reading an absent `status` as `active` (rule 9). */
+declare function memoryStatus(doc: Pick<MemoryFrontmatter, "status">): MemoryStatus;
+/**
+ * Rule 7: a writer only moves `status` from `active` (or absent) to
+ * `superseded` or `archived`, and never out of either. Rewriting the
+ * same status is not a transition and is allowed.
+ */
+declare function isAllowedStatusTransition(from: MemoryStatus | undefined, to: MemoryStatus): boolean;
+/**
+ * Whether a reader may present the item as in force at `now`.
+ *
+ * Rule 10: a `superseded` or `archived` item is not. Rule 11: an
+ * `until` lifetime past its `at` is not. A `while` anchor or a
+ * `session` lifetime needs context outside the document (does the
+ * anchor still hold, which session is current), so this check treats
+ * them as holding; the store that has that context narrows further.
+ */
+declare function isInForce(doc: Pick<MemoryFrontmatter, "status" | "lifetime">, now?: Date): boolean;
+
+/** Thrown by `defineMemory` and `renderMemory` on an invalid item. */
+declare class MemoryValidationError extends Error {
+    /** Every error found, each naming its field path. */
+    readonly issues: readonly MemoryIssue[];
+    /** Path of the first offending field (`""` for the whole document). */
+    readonly field: string;
+    constructor(prefix: string, issues: readonly MemoryIssue[]);
+}
+/** Thrown by `parseMemory` when the markdown has no readable frontmatter. */
+declare class MemoryParseError extends Error {
+    constructor(message: string);
+}
+
+/**
+ * AIP-72 memory/v1 frontmatter zod schema.
+ *
+ * Codegen output of `scripts/scaffold-aip.mjs --aip 72 --slug memory
+ * --doctype MEMORY --schema-only --inline-refs` over
+ * `specs/resources/aip-72/draft/MEMORY.schema.json`. Do not edit the code
+ * below by hand: change the JSON draft, then regenerate.
+ * `scripts/check-spec-drift.mjs` fails CI when the code drifts from the
+ * draft (it does not compare this comment).
+ *
+ * Only `validate.ts` imports this schema. `validateMemory` runs it, and
+ * `defineMemory` (`define-memory.ts`) and `renderMemory` (`markdown.ts`)
+ * validate through `validateMemory`. `index.ts` re-exports it.
+ *
+ * What the codegen cannot express also lives in `validate.ts`: the
+ * root `anyOf` (canonical fields or the legacy id/name/type trio), the
+ * `$defs.lifetime` if/then rules (`until` needs `at`, `while` needs
+ * `anchor`), the unknown-key check on the root and `lifetime` objects
+ * (zod 4 drops it inside the `.and(...)` intersections below), and the
+ * AIP-72 conformance rules that apply to a single document.
+ */
+
+declare const memoryFrontmatterSchema: z.ZodIntersection<z.ZodObject<{
+    schema: z.ZodOptional<z.ZodLiteral<"memory/v1">>;
+    slug: z.ZodOptional<z.ZodString>;
+    kind: z.ZodOptional<z.ZodString>;
+    title: z.ZodOptional<z.ZodString>;
+    updated_at: z.ZodOptional<z.ZodString>;
+    id: z.ZodOptional<z.ZodString>;
+    name: z.ZodOptional<z.ZodString>;
+    type: z.ZodOptional<z.ZodEnum<{
+        user: "user";
+        feedback: "feedback";
+        project: "project";
+        reference: "reference";
+    }>>;
+    description: z.ZodOptional<z.ZodString>;
+    tags: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    polarity: z.ZodOptional<z.ZodEnum<{
+        do: "do";
+        dont: "dont";
+    }>>;
+    lifetime: z.ZodOptional<z.ZodIntersection<z.ZodObject<{
+        kind: z.ZodEnum<{
+            session: "session";
+            durable: "durable";
+            until: "until";
+            while: "while";
+        }>;
+        at: z.ZodOptional<z.ZodString>;
+        anchor: z.ZodOptional<z.ZodObject<{
+            kind: z.ZodEnum<{
+                project: "project";
+                global: "global";
+                task: "task";
+                session: "session";
+                pr: "pr";
+                contact: "contact";
+                agent: "agent";
+                node: "node";
+                operator: "operator";
+            }>;
+            slug: z.ZodOptional<z.ZodString>;
+            id: z.ZodOptional<z.ZodString>;
+            repo: z.ZodOptional<z.ZodString>;
+            number: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>, z.ZodIntersection<z.ZodAny, z.ZodAny>>>;
+    status: z.ZodOptional<z.ZodEnum<{
+        active: "active";
+        superseded: "superseded";
+        archived: "archived";
+    }>>;
+    created: z.ZodOptional<z.ZodString>;
+    written: z.ZodOptional<z.ZodString>;
+    decidedBy: z.ZodOptional<z.ZodObject<{
+        rule: z.ZodOptional<z.ZodString>;
+        source: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    provenance: z.ZodOptional<z.ZodObject<{
+        source: z.ZodOptional<z.ZodString>;
+        sessionId: z.ZodOptional<z.ZodString>;
+        ref: z.ZodOptional<z.ZodString>;
+        quote: z.ZodOptional<z.ZodString>;
+        at: z.ZodOptional<z.ZodString>;
+        extractorVersion: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    evidence: z.ZodOptional<z.ZodObject<{
+        sourceKind: z.ZodOptional<z.ZodString>;
+        trust: z.ZodOptional<z.ZodString>;
+        explicitness: z.ZodOptional<z.ZodString>;
+        corroborations: z.ZodOptional<z.ZodNumber>;
+        contradictsActive: z.ZodOptional<z.ZodBoolean>;
+        impact: z.ZodOptional<z.ZodString>;
+        lifetime: z.ZodOptional<z.ZodIntersection<z.ZodObject<{
+            kind: z.ZodEnum<{
+                session: "session";
+                durable: "durable";
+                until: "until";
+                while: "while";
+            }>;
+            at: z.ZodOptional<z.ZodString>;
+            anchor: z.ZodOptional<z.ZodObject<{
+                kind: z.ZodEnum<{
+                    project: "project";
+                    global: "global";
+                    task: "task";
+                    session: "session";
+                    pr: "pr";
+                    contact: "contact";
+                    agent: "agent";
+                    node: "node";
+                    operator: "operator";
+                }>;
+                slug: z.ZodOptional<z.ZodString>;
+                id: z.ZodOptional<z.ZodString>;
+                repo: z.ZodOptional<z.ZodString>;
+                number: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>, z.ZodIntersection<z.ZodAny, z.ZodAny>>>;
+        anchorsResolved: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        ageHours: z.ZodOptional<z.ZodNumber>;
+        flags: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+    capture: z.ZodOptional<z.ZodObject<{
+        mode: z.ZodOptional<z.ZodEnum<{
+            live: "live";
+            batch: "batch";
+        }>>;
+        producer: z.ZodOptional<z.ZodString>;
+        capturedAt: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    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.
+ *
+ * One small typed assertion (user, feedback, project, reference) about a
+ * principal or its work, with a lifecycle, stored as a markdown file
+ * with YAML frontmatter.
+ *
+ * Spec: https://agentproto.sh/docs/aip-72
+ *
+ * Authoring paths:
+ *   - 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 { 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 };