@ai-agent-forge/plugin-memory 0.85.0

package/dist/entry.js

@@ -0,0 +1,154 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { createMemoryCapability, resolveMemoryMode } from "./capability.js";
+/**
+ * Agent-dir config file channel (D-075 S4 fourth batch): the same path the
+ * host's pre-split `builtinCapabilityConfigPath(agentDir, "builtin.memory")`
+ * resolved for the embedded capability. Hosts that declare `api.host.agentDir`
+ * have this file read here and merged over the manifest config — the exact
+ * merge-over-defaults semantics the embedded `withCapabilityConfig` channel
+ * had. A missing file is the normal unconfigured state; an unreadable file,
+ * invalid JSON, or a non-object payload fails the plugin load explicitly
+ * (D-028: this plugin only, never the session). A host without `agentDir`
+ * loads the plugin with the manifest config alone.
+ */
+const CAPABILITY_CONFIG_RELATIVE_PATH = join("capabilities", "builtin.memory.json");
+/** Reads the agent-dir config channel; `undefined` means "no file" (normal unconfigured state). */
+function readAgentDirConfig(configPath) {
+    if (configPath === undefined)
+        return undefined;
+    let raw;
+    try {
+        raw = readFileSync(configPath, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw new Error(`Failed to read ${configPath}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new Error(`${configPath} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error(`${configPath} must contain a JSON object`);
+    }
+    return parsed;
+}
+/**
+ * The string-valued config key or `undefined`. A present-but-non-string value
+ * (only possible through the raw JSON channels) is reported by the caller —
+ * never silently coerced.
+ */
+function stringConfigValue(config, key) {
+    const raw = config[key];
+    if (raw === undefined)
+        return {};
+    if (typeof raw === "string")
+        return { value: raw };
+    return { invalid: raw };
+}
+/**
+ * Default-export factory consumed by the host's `loadCapabilityPluginFromManifest`.
+ *
+ * Service mapping (D-075 S4 fourth batch): the host facts the embedded
+ * capability received as constructor context are assembled here from
+ * `api.host` and the merged config —
+ * - `api.host.agentDir` roots the durable ledger (`<agentDir>/memory/`) and
+ *   opens the agent-dir config channel;
+ * - `api.host.memoryStorage` → the A1/A2 storage injection face
+ *   (`MemoryStorageComponentsV1`: store/ledger factories plus optional
+ *   vector components); absent = the plugin's built-in local implementation;
+ * - mode resolution reuses the migrated `resolveMemoryMode` with the same
+ *   precedence the host assembler had: explicit config `memoryMode` (host
+ *   configOverride injects it, wiring lands with the host cutover batch) →
+ *   env `AGENT_FORGE_MEMORY_MODE` (read here via the resolver's process.env
+ *   default) → config `memorySettingsMode` (the persistent settings face) →
+ *   legacy alias → off.
+ *
+ * A resolved mode of "off", or a host without `agentDir`, registers NOTHING
+ * (zero tools, zero commands, zero events) with one debug log line — the same
+ * tool-face-absent semantics the embedded capability had for mode=off; the
+ * factory never throws for a disabled configuration.
+ *
+ * `vectorComponents` (the test-only seam) deliberately does NOT ride the
+ * entry: it stays on the library face (`createCapabilityWithVectorComponents`)
+ * for embedders and tests, per the deterministic-mock gate.
+ *
+ * The factory returns its registrations as an array; the wrapper disposes them
+ * in reverse order on plugin teardown — the same disposal semantics as the
+ * host's embedded `syncRegistrationFactory`.
+ */
+export default function createMemoryPluginEntry(api) {
+    const agentDir = api.host.agentDir;
+    if (agentDir === undefined) {
+        // No agent dir = no durable memory location; the tool face stays absent
+        // instead of failing the plugin (the host opted out of disk state).
+        api.logger?.debug("memory plugin idle: host declares no agentDir");
+        return { dispose: () => { } };
+    }
+    const configPath = join(agentDir, CAPABILITY_CONFIG_RELATIVE_PATH);
+    const fileConfig = readAgentDirConfig(configPath);
+    const effectiveConfig = fileConfig === undefined ? api.config : { ...api.config, ...fileConfig };
+    const mode = stringConfigValue(effectiveConfig, "memoryMode");
+    if (mode.invalid !== undefined) {
+        api.logger?.warn(`memoryMode config must be a string; memory stays off (fail-closed)`);
+    }
+    const settingsMode = stringConfigValue(effectiveConfig, "memorySettingsMode");
+    if (settingsMode.invalid !== undefined) {
+        api.logger?.warn(`memorySettingsMode config must be a string; memory stays off (fail-closed)`);
+    }
+    // resolveMemoryMode's env parameter defaults to process.env; passing the
+    // default explicitly keeps the entry's "env read here" contract visible.
+    const resolution = resolveMemoryMode(mode.value, process.env, settingsMode.value);
+    if (resolution.invalidEnvValue !== undefined) {
+        api.logger?.warn(`invalid AGENT_FORGE_MEMORY_MODE value "${resolution.invalidEnvValue}"; memory stays off (fail-closed)`);
+    }
+    if (resolution.invalidSettingsValue !== undefined) {
+        api.logger?.warn(`invalid memory.mode setting "${resolution.invalidSettingsValue}"; memory stays off (fail-closed)`);
+    }
+    if (resolution.mode === "off") {
+        api.logger?.debug("memory plugin idle (mode=off)");
+        return { dispose: () => { } };
+    }
+    const memoryStorage = api.host.memoryStorage;
+    // 宿主重依赖路径注入 (安装店可见性): 装载器把 hostDependencyPaths 并进
+    // manifest config (specifier → 宿主 node_modules 入口绝对路径)。onnxruntime
+    // 供 native 预检; lancedb/transformers 供运行时按绝对路径原生 import (安装店
+    // 副本的裸 import 无法解析)。非字符串值忽略 (fail-closed 由消费侧兜底)。
+    const dependencyPaths = effectiveConfig.hostDependencyPaths;
+    const dependencyPathMap = Array.isArray(dependencyPaths) || typeof dependencyPaths !== "object" || dependencyPaths === null
+        ? undefined
+        : dependencyPaths;
+    const stringDependencyPath = (key) => {
+        const value = dependencyPathMap?.[key];
+        return typeof value === "string" ? value : undefined;
+    };
+    const hostOnnxRuntimeEntryPath = stringDependencyPath("onnxruntimeNode");
+    const hostLancedbEntryPath = stringDependencyPath("lancedb");
+    const hostTransformersEntryPath = stringDependencyPath("transformers");
+    const registrations = createMemoryCapability(api, {
+        agentDir,
+        ...(hostOnnxRuntimeEntryPath === undefined ? {} : { hostOnnxRuntimeEntryPath }),
+        ...(hostLancedbEntryPath === undefined ? {} : { hostLancedbEntryPath }),
+        ...(hostTransformersEntryPath === undefined ? {} : { hostTransformersEntryPath }),
+        memory: {
+            mode: resolution.mode,
+            ...(settingsMode.value === undefined ? {} : { settingsMode: settingsMode.value }),
+        },
+        ...(memoryStorage === undefined ? {} : { storage: memoryStorage }),
+    });
+    return {
+        dispose: () => {
+            for (const registration of [...registrations].reverse()) {
+                // Registration disposal in the capability runtime is synchronous;
+                // void consumes the declared Promise possibility of the contract.
+                void registration.dispose();
+            }
+        },
+    };
+}
+//# sourceMappingURL=entry.js.map

package/dist/entry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entry.js","sourceRoot":"","sources":["../src/entry.ts"],"names":[],"mappings":"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","sourcesContent":["import { readFileSync } from \"node:fs\";\nimport { join } from \"node:path\";\nimport type { CapabilityAPI, PluginConfig, PluginConfigValue } from \"@agent-forge/plugin-sdk\";\nimport { createMemoryCapability, resolveMemoryMode } from \"./capability.ts\";\n\n/**\n * Agent-dir config file channel (D-075 S4 fourth batch): the same path the\n * host's pre-split `builtinCapabilityConfigPath(agentDir, \"builtin.memory\")`\n * resolved for the embedded capability. Hosts that declare `api.host.agentDir`\n * have this file read here and merged over the manifest config — the exact\n * merge-over-defaults semantics the embedded `withCapabilityConfig` channel\n * had. A missing file is the normal unconfigured state; an unreadable file,\n * invalid JSON, or a non-object payload fails the plugin load explicitly\n * (D-028: this plugin only, never the session). A host without `agentDir`\n * loads the plugin with the manifest config alone.\n */\nconst CAPABILITY_CONFIG_RELATIVE_PATH = join(\"capabilities\", \"builtin.memory.json\");\n\n/** Reads the agent-dir config channel; `undefined` means \"no file\" (normal unconfigured state). */\nfunction readAgentDirConfig(configPath: string | undefined): PluginConfig | undefined {\n\tif (configPath === undefined) return undefined;\n\tlet raw: string;\n\ttry {\n\t\traw = readFileSync(configPath, \"utf8\");\n\t} catch (error) {\n\t\tif ((error as NodeJS.ErrnoException).code === \"ENOENT\") return undefined;\n\t\tthrow new Error(`Failed to read ${configPath}: ${error instanceof Error ? error.message : String(error)}`);\n\t}\n\tlet parsed: unknown;\n\ttry {\n\t\tparsed = JSON.parse(raw);\n\t} catch (error) {\n\t\tthrow new Error(`${configPath} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);\n\t}\n\tif (parsed === null || typeof parsed !== \"object\" || Array.isArray(parsed)) {\n\t\tthrow new Error(`${configPath} must contain a JSON object`);\n\t}\n\treturn parsed as PluginConfig;\n}\n\n/**\n * The string-valued config key or `undefined`. A present-but-non-string value\n * (only possible through the raw JSON channels) is reported by the caller —\n * never silently coerced.\n */\nfunction stringConfigValue(\n\tconfig: PluginConfig,\n\tkey: string,\n): { readonly value?: string; readonly invalid?: PluginConfigValue } {\n\tconst raw = config[key];\n\tif (raw === undefined) return {};\n\tif (typeof raw === \"string\") return { value: raw };\n\treturn { invalid: raw };\n}\n\n/**\n * Default-export factory consumed by the host's `loadCapabilityPluginFromManifest`.\n *\n * Service mapping (D-075 S4 fourth batch): the host facts the embedded\n * capability received as constructor context are assembled here from\n * `api.host` and the merged config —\n * - `api.host.agentDir` roots the durable ledger (`<agentDir>/memory/`) and\n *   opens the agent-dir config channel;\n * - `api.host.memoryStorage` → the A1/A2 storage injection face\n *   (`MemoryStorageComponentsV1`: store/ledger factories plus optional\n *   vector components); absent = the plugin's built-in local implementation;\n * - mode resolution reuses the migrated `resolveMemoryMode` with the same\n *   precedence the host assembler had: explicit config `memoryMode` (host\n *   configOverride injects it, wiring lands with the host cutover batch) →\n *   env `AGENT_FORGE_MEMORY_MODE` (read here via the resolver's process.env\n *   default) → config `memorySettingsMode` (the persistent settings face) →\n *   legacy alias → off.\n *\n * A resolved mode of \"off\", or a host without `agentDir`, registers NOTHING\n * (zero tools, zero commands, zero events) with one debug log line — the same\n * tool-face-absent semantics the embedded capability had for mode=off; the\n * factory never throws for a disabled configuration.\n *\n * `vectorComponents` (the test-only seam) deliberately does NOT ride the\n * entry: it stays on the library face (`createCapabilityWithVectorComponents`)\n * for embedders and tests, per the deterministic-mock gate.\n *\n * The factory returns its registrations as an array; the wrapper disposes them\n * in reverse order on plugin teardown — the same disposal semantics as the\n * host's embedded `syncRegistrationFactory`.\n */\nexport default function createMemoryPluginEntry(api: CapabilityAPI): { dispose: () => void } {\n\tconst agentDir = api.host.agentDir;\n\tif (agentDir === undefined) {\n\t\t// No agent dir = no durable memory location; the tool face stays absent\n\t\t// instead of failing the plugin (the host opted out of disk state).\n\t\tapi.logger?.debug(\"memory plugin idle: host declares no agentDir\");\n\t\treturn { dispose: () => {} };\n\t}\n\tconst configPath = join(agentDir, CAPABILITY_CONFIG_RELATIVE_PATH);\n\tconst fileConfig = readAgentDirConfig(configPath);\n\tconst effectiveConfig: PluginConfig = fileConfig === undefined ? api.config : { ...api.config, ...fileConfig };\n\n\tconst mode = stringConfigValue(effectiveConfig, \"memoryMode\");\n\tif (mode.invalid !== undefined) {\n\t\tapi.logger?.warn(`memoryMode config must be a string; memory stays off (fail-closed)`);\n\t}\n\tconst settingsMode = stringConfigValue(effectiveConfig, \"memorySettingsMode\");\n\tif (settingsMode.invalid !== undefined) {\n\t\tapi.logger?.warn(`memorySettingsMode config must be a string; memory stays off (fail-closed)`);\n\t}\n\t// resolveMemoryMode's env parameter defaults to process.env; passing the\n\t// default explicitly keeps the entry's \"env read here\" contract visible.\n\tconst resolution = resolveMemoryMode(mode.value, process.env, settingsMode.value);\n\tif (resolution.invalidEnvValue !== undefined) {\n\t\tapi.logger?.warn(\n\t\t\t`invalid AGENT_FORGE_MEMORY_MODE value \"${resolution.invalidEnvValue}\"; memory stays off (fail-closed)`,\n\t\t);\n\t}\n\tif (resolution.invalidSettingsValue !== undefined) {\n\t\tapi.logger?.warn(\n\t\t\t`invalid memory.mode setting \"${resolution.invalidSettingsValue}\"; memory stays off (fail-closed)`,\n\t\t);\n\t}\n\tif (resolution.mode === \"off\") {\n\t\tapi.logger?.debug(\"memory plugin idle (mode=off)\");\n\t\treturn { dispose: () => {} };\n\t}\n\n\tconst memoryStorage = api.host.memoryStorage;\n\t// 宿主重依赖路径注入 (安装店可见性): 装载器把 hostDependencyPaths 并进\n\t// manifest config (specifier → 宿主 node_modules 入口绝对路径)。onnxruntime\n\t// 供 native 预检; lancedb/transformers 供运行时按绝对路径原生 import (安装店\n\t// 副本的裸 import 无法解析)。非字符串值忽略 (fail-closed 由消费侧兜底)。\n\tconst dependencyPaths = effectiveConfig.hostDependencyPaths;\n\tconst dependencyPathMap: Record<string, PluginConfigValue> | undefined =\n\t\tArray.isArray(dependencyPaths) || typeof dependencyPaths !== \"object\" || dependencyPaths === null\n\t\t\t? undefined\n\t\t\t: (dependencyPaths as Record<string, PluginConfigValue>);\n\tconst stringDependencyPath = (key: string): string | undefined => {\n\t\tconst value = dependencyPathMap?.[key];\n\t\treturn typeof value === \"string\" ? value : undefined;\n\t};\n\tconst hostOnnxRuntimeEntryPath = stringDependencyPath(\"onnxruntimeNode\");\n\tconst hostLancedbEntryPath = stringDependencyPath(\"lancedb\");\n\tconst hostTransformersEntryPath = stringDependencyPath(\"transformers\");\n\tconst registrations = createMemoryCapability(api, {\n\t\tagentDir,\n\t\t...(hostOnnxRuntimeEntryPath === undefined ? {} : { hostOnnxRuntimeEntryPath }),\n\t\t...(hostLancedbEntryPath === undefined ? {} : { hostLancedbEntryPath }),\n\t\t...(hostTransformersEntryPath === undefined ? {} : { hostTransformersEntryPath }),\n\t\tmemory: {\n\t\t\tmode: resolution.mode,\n\t\t\t...(settingsMode.value === undefined ? {} : { settingsMode: settingsMode.value }),\n\t\t},\n\t\t...(memoryStorage === undefined ? {} : { storage: memoryStorage }),\n\t});\n\treturn {\n\t\tdispose: () => {\n\t\t\tfor (const registration of [...registrations].reverse()) {\n\t\t\t\t// Registration disposal in the capability runtime is synchronous;\n\t\t\t\t// void consumes the declared Promise possibility of the contract.\n\t\t\t\tvoid registration.dispose();\n\t\t\t}\n\t\t},\n\t};\n}\n"]}

package/dist/index.d.ts

@@ -0,0 +1,49 @@
+/**
+ * First-party memory capability plugin: the model-facing
+ * memory_write / memory_recall / memory_list / memory_forget surface over the
+ * M5 Memory Foundation, extracted from the host's embedded builtin capability
+ * `agent-forge.builtin.memory` (D-075 S4, fourth batch).
+ *
+ * Library face (`createMemoryCapability(api, context, override?)`) keeps the
+ * explicit-context signature for embedders and tests; the plugin entry
+ * (`./entry.ts`, manifest-loaded) assembles the same context from the host
+ * services (`api.host.agentDir` / `api.host.memoryStorage`) plus the
+ * agent-dir config channel. The 29 Foundation/semantic modules and the
+ * deterministic memory testkit migrate with the capability and are
+ * re-exported here so consumers keep one import face. The memory public
+ * contracts (canonical atom family, store/ledger/vector seams,
+ * `MemoryStorageComponentsV1`, `MEMORY_RECALL_TOOL_NAME`) live in
+ * `@agent-forge/plugin-sdk` and are re-exported through `./capability.ts`.
+ */
+export * from "./capability.ts";
+export * from "./memory/assistant-card.ts";
+export * from "./memory/candidates.ts";
+export * from "./memory/code-memory.ts";
+export * from "./memory/compaction-sequencer.ts";
+export * from "./memory/continuation.ts";
+export * from "./memory/curation.ts";
+export * from "./memory/egress-policy.ts";
+export * from "./memory/embedding-provider.ts";
+export * from "./memory/embedding-reranker.ts";
+export * from "./memory/foundation.ts";
+export * from "./memory/ledger.ts";
+export * from "./memory/lifecycle.ts";
+export * from "./memory/memory-network.ts";
+export * from "./memory/preference-disambiguator.ts";
+export * from "./memory/preference-lifecycle.ts";
+export * from "./memory/preference-promotion.ts";
+export * from "./memory/preference-resolver.ts";
+export * from "./memory/purge.ts";
+export * from "./memory/purge-journal.ts";
+export * from "./memory/recall-agent.ts";
+export * from "./memory/recall-index.ts";
+export * from "./memory/recall-packet.ts";
+export * from "./memory/scheduler.ts";
+export * from "./memory/scheduler-api.ts";
+export * from "./memory/store.ts";
+export * from "./memory/suite-memory.ts";
+export * from "./memory/transfer.ts";
+export * from "./memory/vector-index.ts";
+export * from "./memory/write-budget.ts";
+export * from "./testing/memory-testkit.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,cAAc,iBAAiB,CAAC;AAChC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,wBAAwB,CAAC;AACvC,cAAc,yBAAyB,CAAC;AACxC,cAAc,kCAAkC,CAAC;AACjD,cAAc,0BAA0B,CAAC;AACzC,cAAc,sBAAsB,CAAC;AACrC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,wBAAwB,CAAC;AACvC,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,sCAAsC,CAAC;AACrD,cAAc,kCAAkC,CAAC;AACjD,cAAc,kCAAkC,CAAC;AACjD,cAAc,iCAAiC,CAAC;AAChD,cAAc,mBAAmB,CAAC;AAClC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,0BAA0B,CAAC;AACzC,cAAc,0BAA0B,CAAC;AACzC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,uBAAuB,CAAC;AACtC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,mBAAmB,CAAC;AAClC,cAAc,0BAA0B,CAAC;AACzC,cAAc,sBAAsB,CAAC;AACrC,cAAc,0BAA0B,CAAC;AACzC,cAAc,0BAA0B,CAAC;AACzC,cAAc,6BAA6B,CAAC","sourcesContent":["/**\n * First-party memory capability plugin: the model-facing\n * memory_write / memory_recall / memory_list / memory_forget surface over the\n * M5 Memory Foundation, extracted from the host's embedded builtin capability\n * `agent-forge.builtin.memory` (D-075 S4, fourth batch).\n *\n * Library face (`createMemoryCapability(api, context, override?)`) keeps the\n * explicit-context signature for embedders and tests; the plugin entry\n * (`./entry.ts`, manifest-loaded) assembles the same context from the host\n * services (`api.host.agentDir` / `api.host.memoryStorage`) plus the\n * agent-dir config channel. The 29 Foundation/semantic modules and the\n * deterministic memory testkit migrate with the capability and are\n * re-exported here so consumers keep one import face. The memory public\n * contracts (canonical atom family, store/ledger/vector seams,\n * `MemoryStorageComponentsV1`, `MEMORY_RECALL_TOOL_NAME`) live in\n * `@agent-forge/plugin-sdk` and are re-exported through `./capability.ts`.\n */\n\nexport * from \"./capability.ts\";\nexport * from \"./memory/assistant-card.ts\";\nexport * from \"./memory/candidates.ts\";\nexport * from \"./memory/code-memory.ts\";\nexport * from \"./memory/compaction-sequencer.ts\";\nexport * from \"./memory/continuation.ts\";\nexport * from \"./memory/curation.ts\";\nexport * from \"./memory/egress-policy.ts\";\nexport * from \"./memory/embedding-provider.ts\";\nexport * from \"./memory/embedding-reranker.ts\";\nexport * from \"./memory/foundation.ts\";\nexport * from \"./memory/ledger.ts\";\nexport * from \"./memory/lifecycle.ts\";\nexport * from \"./memory/memory-network.ts\";\nexport * from \"./memory/preference-disambiguator.ts\";\nexport * from \"./memory/preference-lifecycle.ts\";\nexport * from \"./memory/preference-promotion.ts\";\nexport * from \"./memory/preference-resolver.ts\";\nexport * from \"./memory/purge.ts\";\nexport * from \"./memory/purge-journal.ts\";\nexport * from \"./memory/recall-agent.ts\";\nexport * from \"./memory/recall-index.ts\";\nexport * from \"./memory/recall-packet.ts\";\nexport * from \"./memory/scheduler.ts\";\nexport * from \"./memory/scheduler-api.ts\";\nexport * from \"./memory/store.ts\";\nexport * from \"./memory/suite-memory.ts\";\nexport * from \"./memory/transfer.ts\";\nexport * from \"./memory/vector-index.ts\";\nexport * from \"./memory/write-budget.ts\";\nexport * from \"./testing/memory-testkit.ts\";\n"]}

package/dist/index.js

@@ -0,0 +1,49 @@
+/**
+ * First-party memory capability plugin: the model-facing
+ * memory_write / memory_recall / memory_list / memory_forget surface over the
+ * M5 Memory Foundation, extracted from the host's embedded builtin capability
+ * `agent-forge.builtin.memory` (D-075 S4, fourth batch).
+ *
+ * Library face (`createMemoryCapability(api, context, override?)`) keeps the
+ * explicit-context signature for embedders and tests; the plugin entry
+ * (`./entry.ts`, manifest-loaded) assembles the same context from the host
+ * services (`api.host.agentDir` / `api.host.memoryStorage`) plus the
+ * agent-dir config channel. The 29 Foundation/semantic modules and the
+ * deterministic memory testkit migrate with the capability and are
+ * re-exported here so consumers keep one import face. The memory public
+ * contracts (canonical atom family, store/ledger/vector seams,
+ * `MemoryStorageComponentsV1`, `MEMORY_RECALL_TOOL_NAME`) live in
+ * `@agent-forge/plugin-sdk` and are re-exported through `./capability.ts`.
+ */
+export * from "./capability.js";
+export * from "./memory/assistant-card.js";
+export * from "./memory/candidates.js";
+export * from "./memory/code-memory.js";
+export * from "./memory/compaction-sequencer.js";
+export * from "./memory/continuation.js";
+export * from "./memory/curation.js";
+export * from "./memory/egress-policy.js";
+export * from "./memory/embedding-provider.js";
+export * from "./memory/embedding-reranker.js";
+export * from "./memory/foundation.js";
+export * from "./memory/ledger.js";
+export * from "./memory/lifecycle.js";
+export * from "./memory/memory-network.js";
+export * from "./memory/preference-disambiguator.js";
+export * from "./memory/preference-lifecycle.js";
+export * from "./memory/preference-promotion.js";
+export * from "./memory/preference-resolver.js";
+export * from "./memory/purge.js";
+export * from "./memory/purge-journal.js";
+export * from "./memory/recall-agent.js";
+export * from "./memory/recall-index.js";
+export * from "./memory/recall-packet.js";
+export * from "./memory/scheduler.js";
+export * from "./memory/scheduler-api.js";
+export * from "./memory/store.js";
+export * from "./memory/suite-memory.js";
+export * from "./memory/transfer.js";
+export * from "./memory/vector-index.js";
+export * from "./memory/write-budget.js";
+export * from "./testing/memory-testkit.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,cAAc,iBAAiB,CAAC;AAChC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,wBAAwB,CAAC;AACvC,cAAc,yBAAyB,CAAC;AACxC,cAAc,kCAAkC,CAAC;AACjD,cAAc,0BAA0B,CAAC;AACzC,cAAc,sBAAsB,CAAC;AACrC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,wBAAwB,CAAC;AACvC,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,sCAAsC,CAAC;AACrD,cAAc,kCAAkC,CAAC;AACjD,cAAc,kCAAkC,CAAC;AACjD,cAAc,iCAAiC,CAAC;AAChD,cAAc,mBAAmB,CAAC;AAClC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,0BAA0B,CAAC;AACzC,cAAc,0BAA0B,CAAC;AACzC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,uBAAuB,CAAC;AACtC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,mBAAmB,CAAC;AAClC,cAAc,0BAA0B,CAAC;AACzC,cAAc,sBAAsB,CAAC;AACrC,cAAc,0BAA0B,CAAC;AACzC,cAAc,0BAA0B,CAAC;AACzC,cAAc,6BAA6B,CAAC","sourcesContent":["/**\n * First-party memory capability plugin: the model-facing\n * memory_write / memory_recall / memory_list / memory_forget surface over the\n * M5 Memory Foundation, extracted from the host's embedded builtin capability\n * `agent-forge.builtin.memory` (D-075 S4, fourth batch).\n *\n * Library face (`createMemoryCapability(api, context, override?)`) keeps the\n * explicit-context signature for embedders and tests; the plugin entry\n * (`./entry.ts`, manifest-loaded) assembles the same context from the host\n * services (`api.host.agentDir` / `api.host.memoryStorage`) plus the\n * agent-dir config channel. The 29 Foundation/semantic modules and the\n * deterministic memory testkit migrate with the capability and are\n * re-exported here so consumers keep one import face. The memory public\n * contracts (canonical atom family, store/ledger/vector seams,\n * `MemoryStorageComponentsV1`, `MEMORY_RECALL_TOOL_NAME`) live in\n * `@agent-forge/plugin-sdk` and are re-exported through `./capability.ts`.\n */\n\nexport * from \"./capability.ts\";\nexport * from \"./memory/assistant-card.ts\";\nexport * from \"./memory/candidates.ts\";\nexport * from \"./memory/code-memory.ts\";\nexport * from \"./memory/compaction-sequencer.ts\";\nexport * from \"./memory/continuation.ts\";\nexport * from \"./memory/curation.ts\";\nexport * from \"./memory/egress-policy.ts\";\nexport * from \"./memory/embedding-provider.ts\";\nexport * from \"./memory/embedding-reranker.ts\";\nexport * from \"./memory/foundation.ts\";\nexport * from \"./memory/ledger.ts\";\nexport * from \"./memory/lifecycle.ts\";\nexport * from \"./memory/memory-network.ts\";\nexport * from \"./memory/preference-disambiguator.ts\";\nexport * from \"./memory/preference-lifecycle.ts\";\nexport * from \"./memory/preference-promotion.ts\";\nexport * from \"./memory/preference-resolver.ts\";\nexport * from \"./memory/purge.ts\";\nexport * from \"./memory/purge-journal.ts\";\nexport * from \"./memory/recall-agent.ts\";\nexport * from \"./memory/recall-index.ts\";\nexport * from \"./memory/recall-packet.ts\";\nexport * from \"./memory/scheduler.ts\";\nexport * from \"./memory/scheduler-api.ts\";\nexport * from \"./memory/store.ts\";\nexport * from \"./memory/suite-memory.ts\";\nexport * from \"./memory/transfer.ts\";\nexport * from \"./memory/vector-index.ts\";\nexport * from \"./memory/write-budget.ts\";\nexport * from \"./testing/memory-testkit.ts\";\n"]}

package/dist/memory/assistant-card.d.ts

@@ -0,0 +1,31 @@
+import type { MemoryAtomV1 } from "./foundation.ts";
+/** Maximum preference lines on one card (轻量注入, never unbounded). */
+export declare const ASSISTANT_PREFERENCE_CARD_MAX_ENTRIES = 8;
+/**
+ * Renders the preference atoms as a one-line-per-preference card. Non-
+ * preference atoms are ignored; preference atoms without an envelope are
+ * impossible (Foundation validation) and are ignored defensively. Promoted
+ * user-default preferences carry a ⭐ marker (#4). Deterministic: first
+ * `ASSISTANT_PREFERENCE_CARD_MAX_ENTRIES` preferences in input order.
+ */
+export declare function buildAssistantPreferenceCard(atoms: readonly MemoryAtomV1[]): string | undefined;
+export interface LoadAssistantPreferenceCardOptions {
+    /** Agent home directory root of the durable ledgers (`<agentDir>/memory/`). */
+    readonly agentDir: string;
+    /** Foundation owner (isolation principal) the memory capability wrote under. */
+    readonly owner: string;
+    /** The active suite; the card covers its own plus promoted user-default preferences. */
+    readonly suiteId: string;
+}
+/**
+ * Host-side injection entry (统一修复轮 A 交付3 接线通道): reads every durable
+ * ledger of the owner under `<agentDir>/memory/<owner>/ledger-*.jsonl`, replays
+ * the atoms in memory, applies the suite read boundary
+ * ({@link memorySuiteVisibility} — the suite's own preferences plus explicitly
+ * promoted user-default preferences), and renders the preference card. A
+ * missing memory directory (nothing written yet) yields `undefined`; every
+ * other IO error propagates. Malformed ledger lines are skipped by the ledger
+ * loader itself (损坏容错), never failing the session start.
+ */
+export declare function loadAssistantPreferenceCard(options: LoadAssistantPreferenceCardOptions): string | undefined;
+//# sourceMappingURL=assistant-card.d.ts.map

package/dist/memory/assistant-card.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assistant-card.d.ts","sourceRoot":"","sources":["../../src/memory/assistant-card.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAIpD,4EAAoE;AACpE,eAAO,MAAM,qCAAqC,IAAI,CAAC;AAkCvD;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,SAAS,YAAY,EAAE,GAAG,MAAM,GAAG,SAAS,CAU/F;AAED,MAAM,WAAW,kCAAkC;IAClD,+EAA+E;IAC/E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,gFAAgF;IAChF,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,wFAAwF;IACxF,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;GASG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,kCAAkC,GAAG,MAAM,GAAG,SAAS,CAqB3G","sourcesContent":["/**\n * Assistant preference card (统一修复轮 A, 方案系统设计 §6.1) — the lightweight\n * user-profile card injected into the assistant suite's context at session\n * start (召回形态: \"会话开始的轻量注入（用户画像卡）\").\n *\n * Pure formatter: the caller passes the atoms already scoped by the suite read\n * boundary (the suite's own preferences plus explicitly promoted user-default\n * preferences, e.g. `store.listForSuite(...)` results); this module only picks\n * preference atoms and renders at most one line per preference. No content →\n * `undefined`, so hosts can skip the injection entirely instead of emitting an\n * empty section. The output is deterministic: input order, capped entries.\n * The card closes with a priority note (#6): the card is the pre-loaded\n * summary injected at session start, while memory_recall is the live query —\n * the model is told to consult the latter for additional context or recent\n * updates. Promoted user-default preferences (explicitly confirmed, the one\n * cross-suite class) are starred (#4) so the model can tell them apart from\n * suite-local preferences.\n */\nimport { readdirSync } from \"node:fs\";\nimport { join } from \"node:path\";\nimport type { JsonValue } from \"@agent-forge/plugin-sdk\";\nimport type { MemoryAtomV1 } from \"./foundation.ts\";\nimport { memorySuiteVisibility } from \"./foundation.ts\";\nimport { createDurableMemoryLedger } from \"./ledger.ts\";\n\n/** Maximum preference lines on one card (轻量注入, never unbounded). */\nexport const ASSISTANT_PREFERENCE_CARD_MAX_ENTRIES = 8;\n\nconst CARD_HEADER = \"User preference card (from memory):\";\n/**\n * Priority note appended to every card (#6): pre-loaded summary vs live\n * recall. Pinned verbatim by test/memory-assistant-card.test.ts.\n */\nconst CARD_PRELOADED_NOTE =\n\t\"(These preferences are pre-loaded. Use memory_recall to check for additional context or recent updates.)\";\nconst PROMOTED_PREFERENCE_MARKER = \"⭐\";\nconst LEDGER_DIR_NAME = \"memory\";\nconst LEDGER_FILE_PREFIX = \"ledger-\";\nconst LEDGER_FILE_SUFFIX = \".jsonl\";\n\nfunction preferenceValueText(value: JsonValue): string {\n\treturn typeof value === \"string\" ? value : JSON.stringify(value);\n}\n\n/**\n * The explicitly promoted user-default preference marker (#4): the same\n * predicate {@link memorySuiteVisibility} uses for its cross-suite promoted\n * arm — scope.level \"user-default\" WITH `confirmedAt`, set only by the\n * explicit promotion channel. Declared here because the card formatter must\n * distinguish promoted entries without widening the foundation module's\n * exports.\n */\nfunction isPromotedUserDefaultPreference(atom: MemoryAtomV1): boolean {\n\treturn (\n\t\tatom.memoryKind === \"preference\" &&\n\t\tatom.preference?.scope.level === \"user-default\" &&\n\t\tatom.preference.confirmedAt !== undefined\n\t);\n}\n\n/**\n * Renders the preference atoms as a one-line-per-preference card. Non-\n * preference atoms are ignored; preference atoms without an envelope are\n * impossible (Foundation validation) and are ignored defensively. Promoted\n * user-default preferences carry a ⭐ marker (#4). Deterministic: first\n * `ASSISTANT_PREFERENCE_CARD_MAX_ENTRIES` preferences in input order.\n */\nexport function buildAssistantPreferenceCard(atoms: readonly MemoryAtomV1[]): string | undefined {\n\tconst lines: string[] = [];\n\tfor (const atom of atoms) {\n\t\tif (lines.length >= ASSISTANT_PREFERENCE_CARD_MAX_ENTRIES) break;\n\t\tif (atom.memoryKind !== \"preference\" || atom.preference === undefined) continue;\n\t\tconst marker = isPromotedUserDefaultPreference(atom) ? `${PROMOTED_PREFERENCE_MARKER} ` : \"\";\n\t\tlines.push(`- ${marker}[${atom.preference.subject}] ${preferenceValueText(atom.preference.preferredValue)}`);\n\t}\n\tif (lines.length === 0) return undefined;\n\treturn [CARD_HEADER, ...lines, CARD_PRELOADED_NOTE].join(\"\\n\");\n}\n\nexport interface LoadAssistantPreferenceCardOptions {\n\t/** Agent home directory root of the durable ledgers (`<agentDir>/memory/`). */\n\treadonly agentDir: string;\n\t/** Foundation owner (isolation principal) the memory capability wrote under. */\n\treadonly owner: string;\n\t/** The active suite; the card covers its own plus promoted user-default preferences. */\n\treadonly suiteId: string;\n}\n\n/**\n * Host-side injection entry (统一修复轮 A 交付3 接线通道): reads every durable\n * ledger of the owner under `<agentDir>/memory/<owner>/ledger-*.jsonl`, replays\n * the atoms in memory, applies the suite read boundary\n * ({@link memorySuiteVisibility} — the suite's own preferences plus explicitly\n * promoted user-default preferences), and renders the preference card. A\n * missing memory directory (nothing written yet) yields `undefined`; every\n * other IO error propagates. Malformed ledger lines are skipped by the ledger\n * loader itself (损坏容错), never failing the session start.\n */\nexport function loadAssistantPreferenceCard(options: LoadAssistantPreferenceCardOptions): string | undefined {\n\tif (options.owner.trim() === \"\") throw new Error(\"loadAssistantPreferenceCard owner must be a non-empty string\");\n\tif (options.suiteId.trim() === \"\") throw new Error(\"loadAssistantPreferenceCard suiteId must be a non-empty string\");\n\tconst ledgerDir = join(options.agentDir, LEDGER_DIR_NAME, options.owner);\n\tlet files: string[];\n\ttry {\n\t\tfiles = readdirSync(ledgerDir).filter(\n\t\t\t(name) => name.startsWith(LEDGER_FILE_PREFIX) && name.endsWith(LEDGER_FILE_SUFFIX),\n\t\t);\n\t} catch (error) {\n\t\tif ((error as NodeJS.ErrnoException).code === \"ENOENT\") return undefined;\n\t\tthrow error;\n\t}\n\tconst visible: MemoryAtomV1[] = [];\n\tfor (const file of files) {\n\t\tfor (const atom of createDurableMemoryLedger({ path: join(ledgerDir, file) }).load().atoms) {\n\t\t\tif (atom.memoryKind !== \"preference\" || atom.preference === undefined) continue;\n\t\t\tif (memorySuiteVisibility(atom, options.suiteId) === \"visible\") visible.push(atom);\n\t\t}\n\t}\n\treturn buildAssistantPreferenceCard(visible);\n}\n"]}

package/dist/memory/assistant-card.js

@@ -0,0 +1,108 @@
+/**
+ * Assistant preference card (统一修复轮 A, 方案系统设计 §6.1) — the lightweight
+ * user-profile card injected into the assistant suite's context at session
+ * start (召回形态: "会话开始的轻量注入（用户画像卡）").
+ *
+ * Pure formatter: the caller passes the atoms already scoped by the suite read
+ * boundary (the suite's own preferences plus explicitly promoted user-default
+ * preferences, e.g. `store.listForSuite(...)` results); this module only picks
+ * preference atoms and renders at most one line per preference. No content →
+ * `undefined`, so hosts can skip the injection entirely instead of emitting an
+ * empty section. The output is deterministic: input order, capped entries.
+ * The card closes with a priority note (#6): the card is the pre-loaded
+ * summary injected at session start, while memory_recall is the live query —
+ * the model is told to consult the latter for additional context or recent
+ * updates. Promoted user-default preferences (explicitly confirmed, the one
+ * cross-suite class) are starred (#4) so the model can tell them apart from
+ * suite-local preferences.
+ */
+import { readdirSync } from "node:fs";
+import { join } from "node:path";
+import { memorySuiteVisibility } from "./foundation.js";
+import { createDurableMemoryLedger } from "./ledger.js";
+/** Maximum preference lines on one card (轻量注入, never unbounded). */
+export const ASSISTANT_PREFERENCE_CARD_MAX_ENTRIES = 8;
+const CARD_HEADER = "User preference card (from memory):";
+/**
+ * Priority note appended to every card (#6): pre-loaded summary vs live
+ * recall. Pinned verbatim by test/memory-assistant-card.test.ts.
+ */
+const CARD_PRELOADED_NOTE = "(These preferences are pre-loaded. Use memory_recall to check for additional context or recent updates.)";
+const PROMOTED_PREFERENCE_MARKER = "⭐";
+const LEDGER_DIR_NAME = "memory";
+const LEDGER_FILE_PREFIX = "ledger-";
+const LEDGER_FILE_SUFFIX = ".jsonl";
+function preferenceValueText(value) {
+    return typeof value === "string" ? value : JSON.stringify(value);
+}
+/**
+ * The explicitly promoted user-default preference marker (#4): the same
+ * predicate {@link memorySuiteVisibility} uses for its cross-suite promoted
+ * arm — scope.level "user-default" WITH `confirmedAt`, set only by the
+ * explicit promotion channel. Declared here because the card formatter must
+ * distinguish promoted entries without widening the foundation module's
+ * exports.
+ */
+function isPromotedUserDefaultPreference(atom) {
+    return (atom.memoryKind === "preference" &&
+        atom.preference?.scope.level === "user-default" &&
+        atom.preference.confirmedAt !== undefined);
+}
+/**
+ * Renders the preference atoms as a one-line-per-preference card. Non-
+ * preference atoms are ignored; preference atoms without an envelope are
+ * impossible (Foundation validation) and are ignored defensively. Promoted
+ * user-default preferences carry a ⭐ marker (#4). Deterministic: first
+ * `ASSISTANT_PREFERENCE_CARD_MAX_ENTRIES` preferences in input order.
+ */
+export function buildAssistantPreferenceCard(atoms) {
+    const lines = [];
+    for (const atom of atoms) {
+        if (lines.length >= ASSISTANT_PREFERENCE_CARD_MAX_ENTRIES)
+            break;
+        if (atom.memoryKind !== "preference" || atom.preference === undefined)
+            continue;
+        const marker = isPromotedUserDefaultPreference(atom) ? `${PROMOTED_PREFERENCE_MARKER} ` : "";
+        lines.push(`- ${marker}[${atom.preference.subject}] ${preferenceValueText(atom.preference.preferredValue)}`);
+    }
+    if (lines.length === 0)
+        return undefined;
+    return [CARD_HEADER, ...lines, CARD_PRELOADED_NOTE].join("\n");
+}
+/**
+ * Host-side injection entry (统一修复轮 A 交付3 接线通道): reads every durable
+ * ledger of the owner under `<agentDir>/memory/<owner>/ledger-*.jsonl`, replays
+ * the atoms in memory, applies the suite read boundary
+ * ({@link memorySuiteVisibility} — the suite's own preferences plus explicitly
+ * promoted user-default preferences), and renders the preference card. A
+ * missing memory directory (nothing written yet) yields `undefined`; every
+ * other IO error propagates. Malformed ledger lines are skipped by the ledger
+ * loader itself (损坏容错), never failing the session start.
+ */
+export function loadAssistantPreferenceCard(options) {
+    if (options.owner.trim() === "")
+        throw new Error("loadAssistantPreferenceCard owner must be a non-empty string");
+    if (options.suiteId.trim() === "")
+        throw new Error("loadAssistantPreferenceCard suiteId must be a non-empty string");
+    const ledgerDir = join(options.agentDir, LEDGER_DIR_NAME, options.owner);
+    let files;
+    try {
+        files = readdirSync(ledgerDir).filter((name) => name.startsWith(LEDGER_FILE_PREFIX) && name.endsWith(LEDGER_FILE_SUFFIX));
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+    const visible = [];
+    for (const file of files) {
+        for (const atom of createDurableMemoryLedger({ path: join(ledgerDir, file) }).load().atoms) {
+            if (atom.memoryKind !== "preference" || atom.preference === undefined)
+                continue;
+            if (memorySuiteVisibility(atom, options.suiteId) === "visible")
+                visible.push(atom);
+        }
+    }
+    return buildAssistantPreferenceCard(visible);
+}
+//# sourceMappingURL=assistant-card.js.map

package/dist/memory/assistant-card.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assistant-card.js","sourceRoot":"","sources":["../../src/memory/assistant-card.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Assistant preference card (统一修复轮 A, 方案系统设计 §6.1) — the lightweight\n * user-profile card injected into the assistant suite's context at session\n * start (召回形态: \"会话开始的轻量注入（用户画像卡）\").\n *\n * Pure formatter: the caller passes the atoms already scoped by the suite read\n * boundary (the suite's own preferences plus explicitly promoted user-default\n * preferences, e.g. `store.listForSuite(...)` results); this module only picks\n * preference atoms and renders at most one line per preference. No content →\n * `undefined`, so hosts can skip the injection entirely instead of emitting an\n * empty section. The output is deterministic: input order, capped entries.\n * The card closes with a priority note (#6): the card is the pre-loaded\n * summary injected at session start, while memory_recall is the live query —\n * the model is told to consult the latter for additional context or recent\n * updates. Promoted user-default preferences (explicitly confirmed, the one\n * cross-suite class) are starred (#4) so the model can tell them apart from\n * suite-local preferences.\n */\nimport { readdirSync } from \"node:fs\";\nimport { join } from \"node:path\";\nimport type { JsonValue } from \"@agent-forge/plugin-sdk\";\nimport type { MemoryAtomV1 } from \"./foundation.ts\";\nimport { memorySuiteVisibility } from \"./foundation.ts\";\nimport { createDurableMemoryLedger } from \"./ledger.ts\";\n\n/** Maximum preference lines on one card (轻量注入, never unbounded). */\nexport const ASSISTANT_PREFERENCE_CARD_MAX_ENTRIES = 8;\n\nconst CARD_HEADER = \"User preference card (from memory):\";\n/**\n * Priority note appended to every card (#6): pre-loaded summary vs live\n * recall. Pinned verbatim by test/memory-assistant-card.test.ts.\n */\nconst CARD_PRELOADED_NOTE =\n\t\"(These preferences are pre-loaded. Use memory_recall to check for additional context or recent updates.)\";\nconst PROMOTED_PREFERENCE_MARKER = \"⭐\";\nconst LEDGER_DIR_NAME = \"memory\";\nconst LEDGER_FILE_PREFIX = \"ledger-\";\nconst LEDGER_FILE_SUFFIX = \".jsonl\";\n\nfunction preferenceValueText(value: JsonValue): string {\n\treturn typeof value === \"string\" ? value : JSON.stringify(value);\n}\n\n/**\n * The explicitly promoted user-default preference marker (#4): the same\n * predicate {@link memorySuiteVisibility} uses for its cross-suite promoted\n * arm — scope.level \"user-default\" WITH `confirmedAt`, set only by the\n * explicit promotion channel. Declared here because the card formatter must\n * distinguish promoted entries without widening the foundation module's\n * exports.\n */\nfunction isPromotedUserDefaultPreference(atom: MemoryAtomV1): boolean {\n\treturn (\n\t\tatom.memoryKind === \"preference\" &&\n\t\tatom.preference?.scope.level === \"user-default\" &&\n\t\tatom.preference.confirmedAt !== undefined\n\t);\n}\n\n/**\n * Renders the preference atoms as a one-line-per-preference card. Non-\n * preference atoms are ignored; preference atoms without an envelope are\n * impossible (Foundation validation) and are ignored defensively. Promoted\n * user-default preferences carry a ⭐ marker (#4). Deterministic: first\n * `ASSISTANT_PREFERENCE_CARD_MAX_ENTRIES` preferences in input order.\n */\nexport function buildAssistantPreferenceCard(atoms: readonly MemoryAtomV1[]): string | undefined {\n\tconst lines: string[] = [];\n\tfor (const atom of atoms) {\n\t\tif (lines.length >= ASSISTANT_PREFERENCE_CARD_MAX_ENTRIES) break;\n\t\tif (atom.memoryKind !== \"preference\" || atom.preference === undefined) continue;\n\t\tconst marker = isPromotedUserDefaultPreference(atom) ? `${PROMOTED_PREFERENCE_MARKER} ` : \"\";\n\t\tlines.push(`- ${marker}[${atom.preference.subject}] ${preferenceValueText(atom.preference.preferredValue)}`);\n\t}\n\tif (lines.length === 0) return undefined;\n\treturn [CARD_HEADER, ...lines, CARD_PRELOADED_NOTE].join(\"\\n\");\n}\n\nexport interface LoadAssistantPreferenceCardOptions {\n\t/** Agent home directory root of the durable ledgers (`<agentDir>/memory/`). */\n\treadonly agentDir: string;\n\t/** Foundation owner (isolation principal) the memory capability wrote under. */\n\treadonly owner: string;\n\t/** The active suite; the card covers its own plus promoted user-default preferences. */\n\treadonly suiteId: string;\n}\n\n/**\n * Host-side injection entry (统一修复轮 A 交付3 接线通道): reads every durable\n * ledger of the owner under `<agentDir>/memory/<owner>/ledger-*.jsonl`, replays\n * the atoms in memory, applies the suite read boundary\n * ({@link memorySuiteVisibility} — the suite's own preferences plus explicitly\n * promoted user-default preferences), and renders the preference card. A\n * missing memory directory (nothing written yet) yields `undefined`; every\n * other IO error propagates. Malformed ledger lines are skipped by the ledger\n * loader itself (损坏容错), never failing the session start.\n */\nexport function loadAssistantPreferenceCard(options: LoadAssistantPreferenceCardOptions): string | undefined {\n\tif (options.owner.trim() === \"\") throw new Error(\"loadAssistantPreferenceCard owner must be a non-empty string\");\n\tif (options.suiteId.trim() === \"\") throw new Error(\"loadAssistantPreferenceCard suiteId must be a non-empty string\");\n\tconst ledgerDir = join(options.agentDir, LEDGER_DIR_NAME, options.owner);\n\tlet files: string[];\n\ttry {\n\t\tfiles = readdirSync(ledgerDir).filter(\n\t\t\t(name) => name.startsWith(LEDGER_FILE_PREFIX) && name.endsWith(LEDGER_FILE_SUFFIX),\n\t\t);\n\t} catch (error) {\n\t\tif ((error as NodeJS.ErrnoException).code === \"ENOENT\") return undefined;\n\t\tthrow error;\n\t}\n\tconst visible: MemoryAtomV1[] = [];\n\tfor (const file of files) {\n\t\tfor (const atom of createDurableMemoryLedger({ path: join(ledgerDir, file) }).load().atoms) {\n\t\t\tif (atom.memoryKind !== \"preference\" || atom.preference === undefined) continue;\n\t\t\tif (memorySuiteVisibility(atom, options.suiteId) === \"visible\") visible.push(atom);\n\t\t}\n\t}\n\treturn buildAssistantPreferenceCard(visible);\n}\n"]}

package/dist/memory/candidates.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Memory Foundation — minimal observation/candidate/commit state machine
+ * (1C.2).
+ *
+ * The Foundation validates sources, revisions, idempotency, and structural
+ * state only. Accept/reject are public state transitions recorded in an
+ * immutable transition log; nothing is silently dropped. Idempotency identity
+ * is `(owner, observationId)`: re-observing the same key returns the existing
+ * record and never duplicates a commit.
+ *
+ * States: observed → candidate → committed, or → rejected (terminal, with
+ * reason). Lifecycle beyond commit (decay/archive/purge) belongs to the
+ * lifecycle manager slices.
+ */
+import type { JsonValue } from "@agent-forge/plugin-sdk";
+import type { MemoryAtomV1, MemoryScopeV1 } from "./foundation.ts";
+import type { CommittedMemoryV1, MemoryStoreV1 } from "./store.ts";
+export type MemoryCandidateStateV1 = "observed" | "candidate" | "committed" | "rejected";
+export interface MemoryObservationInputV1<TPayload extends JsonValue = JsonValue> {
+    readonly owner: string;
+    readonly observationId: string;
+    /** The unvalidated draft atom; its `observationId` field must match the observation. */
+    readonly draft: MemoryAtomV1<TPayload>;
+}
+export interface MemoryStateTransitionV1 {
+    readonly from: MemoryCandidateStateV1 | null;
+    readonly to: MemoryCandidateStateV1;
+    readonly at: number;
+    readonly reason?: string;
+}
+export interface MemoryCandidateRecordV1<TPayload extends JsonValue = JsonValue> {
+    readonly key: string;
+    readonly owner: string;
+    readonly observationId: string;
+    readonly state: MemoryCandidateStateV1;
+    /** Set from `candidate` onward: the validated, frozen draft. */
+    readonly atom?: MemoryAtomV1<TPayload>;
+    /** Set once committed: the store-assigned record. */
+    readonly committed?: CommittedMemoryV1<TPayload>;
+    /** Set when rejected: the structural reason the draft failed. */
+    readonly rejectedReason?: string;
+    readonly transitions: readonly MemoryStateTransitionV1[];
+}
+export interface MemoryObserveResultV1<TPayload extends JsonValue = JsonValue> {
+    readonly record: MemoryCandidateRecordV1<TPayload>;
+    /** True when the (owner, observationId) identity already existed. */
+    readonly deduped: boolean;
+}
+export interface MemoryCandidateMachineV1 {
+    observe<TPayload extends JsonValue = JsonValue>(input: MemoryObservationInputV1<TPayload>): MemoryObserveResultV1<TPayload>;
+    /** Promotes a candidate into the Foundation ledger (1C.1b store). */
+    accept(observationId: string, owner: string, options?: {
+        readonly retentionModeId?: string;
+    }): CommittedMemoryV1;
+    /** Explicitly rejects a candidate; the reason becomes part of the audit log. */
+    reject(observationId: string, owner: string, reason: string): MemoryCandidateRecordV1;
+    stateOf(observationId: string, owner: string): MemoryCandidateRecordV1 | undefined;
+}
+/** Creates the deterministic candidate state machine over a 1C.1b store. */
+export declare function createMemoryCandidateMachine(options: {
+    readonly store: MemoryStoreV1;
+    readonly now?: () => number;
+}): MemoryCandidateMachineV1;
+export type { MemoryScopeV1 };
+//# sourceMappingURL=candidates.d.ts.map

package/dist/memory/candidates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"candidates.d.ts","sourceRoot":"","sources":["../../src/memory/candidates.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AACzD,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAEnE,OAAO,KAAK,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEnE,MAAM,MAAM,sBAAsB,GAAG,UAAU,GAAG,WAAW,GAAG,WAAW,GAAG,UAAU,CAAC;AAEzF,MAAM,WAAW,wBAAwB,CAAC,QAAQ,SAAS,SAAS,GAAG,SAAS;IAC/E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,wFAAwF;IACxF,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC,QAAQ,CAAC,CAAC;CACvC;AAED,MAAM,WAAW,uBAAuB;IACvC,QAAQ,CAAC,IAAI,EAAE,sBAAsB,GAAG,IAAI,CAAC;IAC7C,QAAQ,CAAC,EAAE,EAAE,sBAAsB,CAAC;IACpC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,uBAAuB,CAAC,QAAQ,SAAS,SAAS,GAAG,SAAS;IAC9E,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,KAAK,EAAE,sBAAsB,CAAC;IACvC,gEAAgE;IAChE,QAAQ,CAAC,IAAI,CAAC,EAAE,YAAY,CAAC,QAAQ,CAAC,CAAC;IACvC,qDAAqD;IACrD,QAAQ,CAAC,SAAS,CAAC,EAAE,iBAAiB,CAAC,QAAQ,CAAC,CAAC;IACjD,iEAAiE;IACjE,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,WAAW,EAAE,SAAS,uBAAuB,EAAE,CAAC;CACzD;AAED,MAAM,WAAW,qBAAqB,CAAC,QAAQ,SAAS,SAAS,GAAG,SAAS;IAC5E,QAAQ,CAAC,MAAM,EAAE,uBAAuB,CAAC,QAAQ,CAAC,CAAC;IACnD,qEAAqE;IACrE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,wBAAwB;IACxC,OAAO,CAAC,QAAQ,SAAS,SAAS,GAAG,SAAS,EAC7C,KAAK,EAAE,wBAAwB,CAAC,QAAQ,CAAC,GACvC,qBAAqB,CAAC,QAAQ,CAAC,CAAC;IACnC,qEAAqE;IACrE,MAAM,CAAC,aAAa,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,iBAAiB,CAAC;IACjH,gFAAgF;IAChF,MAAM,CAAC,aAAa,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,uBAAuB,CAAC;IACtF,OAAO,CAAC,aAAa,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,uBAAuB,GAAG,SAAS,CAAC;CACnF;AAED,4EAA4E;AAC5E,wBAAgB,4BAA4B,CAAC,OAAO,EAAE;IACrD,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;IAC9B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CAC5B,GAAG,wBAAwB,CA2G3B;AAMD,YAAY,EAAE,aAAa,EAAE,CAAC","sourcesContent":["/**\n * Memory Foundation — minimal observation/candidate/commit state machine\n * (1C.2).\n *\n * The Foundation validates sources, revisions, idempotency, and structural\n * state only. Accept/reject are public state transitions recorded in an\n * immutable transition log; nothing is silently dropped. Idempotency identity\n * is `(owner, observationId)`: re-observing the same key returns the existing\n * record and never duplicates a commit.\n *\n * States: observed → candidate → committed, or → rejected (terminal, with\n * reason). Lifecycle beyond commit (decay/archive/purge) belongs to the\n * lifecycle manager slices.\n */\nimport type { JsonValue } from \"@agent-forge/plugin-sdk\";\nimport type { MemoryAtomV1, MemoryScopeV1 } from \"./foundation.ts\";\nimport { memoryObservationKey, validateMemoryAtomV1 } from \"./foundation.ts\";\nimport type { CommittedMemoryV1, MemoryStoreV1 } from \"./store.ts\";\n\nexport type MemoryCandidateStateV1 = \"observed\" | \"candidate\" | \"committed\" | \"rejected\";\n\nexport interface MemoryObservationInputV1<TPayload extends JsonValue = JsonValue> {\n\treadonly owner: string;\n\treadonly observationId: string;\n\t/** The unvalidated draft atom; its `observationId` field must match the observation. */\n\treadonly draft: MemoryAtomV1<TPayload>;\n}\n\nexport interface MemoryStateTransitionV1 {\n\treadonly from: MemoryCandidateStateV1 | null;\n\treadonly to: MemoryCandidateStateV1;\n\treadonly at: number;\n\treadonly reason?: string;\n}\n\nexport interface MemoryCandidateRecordV1<TPayload extends JsonValue = JsonValue> {\n\treadonly key: string;\n\treadonly owner: string;\n\treadonly observationId: string;\n\treadonly state: MemoryCandidateStateV1;\n\t/** Set from `candidate` onward: the validated, frozen draft. */\n\treadonly atom?: MemoryAtomV1<TPayload>;\n\t/** Set once committed: the store-assigned record. */\n\treadonly committed?: CommittedMemoryV1<TPayload>;\n\t/** Set when rejected: the structural reason the draft failed. */\n\treadonly rejectedReason?: string;\n\treadonly transitions: readonly MemoryStateTransitionV1[];\n}\n\nexport interface MemoryObserveResultV1<TPayload extends JsonValue = JsonValue> {\n\treadonly record: MemoryCandidateRecordV1<TPayload>;\n\t/** True when the (owner, observationId) identity already existed. */\n\treadonly deduped: boolean;\n}\n\nexport interface MemoryCandidateMachineV1 {\n\tobserve<TPayload extends JsonValue = JsonValue>(\n\t\tinput: MemoryObservationInputV1<TPayload>,\n\t): MemoryObserveResultV1<TPayload>;\n\t/** Promotes a candidate into the Foundation ledger (1C.1b store). */\n\taccept(observationId: string, owner: string, options?: { readonly retentionModeId?: string }): CommittedMemoryV1;\n\t/** Explicitly rejects a candidate; the reason becomes part of the audit log. */\n\treject(observationId: string, owner: string, reason: string): MemoryCandidateRecordV1;\n\tstateOf(observationId: string, owner: string): MemoryCandidateRecordV1 | undefined;\n}\n\n/** Creates the deterministic candidate state machine over a 1C.1b store. */\nexport function createMemoryCandidateMachine(options: {\n\treadonly store: MemoryStoreV1;\n\treadonly now?: () => number;\n}): MemoryCandidateMachineV1 {\n\tconst store = options.store;\n\tconst now = options.now ?? (() => Date.now());\n\tconst records = new Map<string, MemoryCandidateRecordV1<JsonValue>>();\n\n\tconst keyOf = (owner: string, observationId: string): string => memoryObservationKey(owner, observationId);\n\n\tconst appendTransition = (\n\t\trecord: MemoryCandidateRecordV1<JsonValue>,\n\t\tto: MemoryCandidateStateV1,\n\t\tpatch: Partial<MemoryCandidateRecordV1<JsonValue>> = {},\n\t\treason?: string,\n\t): MemoryCandidateRecordV1<JsonValue> => {\n\t\tconst transition: MemoryStateTransitionV1 = Object.freeze({\n\t\t\tfrom: record.state,\n\t\t\tto,\n\t\t\tat: now(),\n\t\t\t...(reason === undefined ? {} : { reason }),\n\t\t});\n\t\tconst next: MemoryCandidateRecordV1<JsonValue> = Object.freeze({\n\t\t\t...record,\n\t\t\t...patch,\n\t\t\tstate: to,\n\t\t\ttransitions: Object.freeze([...record.transitions, transition]),\n\t\t});\n\t\trecords.set(record.key, next);\n\t\treturn next;\n\t};\n\n\treturn {\n\t\tobserve<TPayload extends JsonValue = JsonValue>(\n\t\t\tinput: MemoryObservationInputV1<TPayload>,\n\t\t): MemoryObserveResultV1<TPayload> {\n\t\t\tassertNonEmptyString(input.owner, \"observation owner\");\n\t\t\tassertNonEmptyString(input.observationId, \"observation observationId\");\n\t\t\tconst key = keyOf(input.owner, input.observationId);\n\t\t\tconst existing = records.get(key);\n\t\t\tif (existing) return { record: existing as MemoryCandidateRecordV1<TPayload>, deduped: true };\n\n\t\t\tconst at = now();\n\t\t\tconst initial: MemoryCandidateRecordV1<TPayload> = Object.freeze({\n\t\t\t\tkey,\n\t\t\t\towner: input.owner,\n\t\t\t\tobservationId: input.observationId,\n\t\t\t\tstate: \"observed\" as const,\n\t\t\t\ttransitions: Object.freeze([Object.freeze({ from: null, to: \"observed\" as const, at })]),\n\t\t\t});\n\n\t\t\t// Structural gate 1 — identity consistency: the draft must claim the\n\t\t\t// same observationId it is submitted under.\n\t\t\tif (input.draft.observationId !== input.observationId) {\n\t\t\t\tconst rejected = appendTransition(\n\t\t\t\t\tinitial,\n\t\t\t\t\t\"rejected\",\n\t\t\t\t\t{ rejectedReason: \"Draft atom observationId does not match the observation identity\" },\n\t\t\t\t\t\"observation identity mismatch\",\n\t\t\t\t);\n\t\t\t\treturn { record: rejected as MemoryCandidateRecordV1<TPayload>, deduped: false };\n\t\t\t}\n\n\t\t\t// Structural gate 2 — full canonical atom validation (schema, sources,\n\t\t\t// revisions, enums, JSON safety). Failures are explicit rejections.\n\t\t\tlet atom: MemoryAtomV1<TPayload>;\n\t\t\ttry {\n\t\t\t\tatom = validateMemoryAtomV1<TPayload>(input.draft);\n\t\t\t\tif (atom.owner !== input.owner) throw new Error(\"Draft atom owner does not match the observation owner\");\n\t\t\t} catch (error) {\n\t\t\t\t// v8 ignore next -- 校验器只抛 Error 对象\n\t\t\t\tconst reason = error instanceof Error ? error.message : String(error);\n\t\t\t\tconst rejected = appendTransition(initial, \"rejected\", { rejectedReason: reason }, reason);\n\t\t\t\treturn { record: rejected as MemoryCandidateRecordV1<TPayload>, deduped: false };\n\t\t\t}\n\n\t\t\tconst candidate = appendTransition(initial, \"candidate\", { atom });\n\t\t\treturn { record: candidate as MemoryCandidateRecordV1<TPayload>, deduped: false };\n\t\t},\n\n\t\taccept(observationId, owner, acceptOptions) {\n\t\t\tconst key = keyOf(owner, observationId);\n\t\t\tconst record = records.get(key);\n\t\t\tif (!record) throw new Error(`Unknown observation: ${observationId}`);\n\t\t\tif (record.state === \"committed\" && record.committed) {\n\t\t\t\t// Idempotent accept: the store commit is never repeated.\n\t\t\t\treturn record.committed;\n\t\t\t}\n\t\t\tif (record.state !== \"candidate\" || !record.atom) {\n\t\t\t\tthrow new Error(`Observation ${observationId} is ${record.state} and cannot be accepted`);\n\t\t\t}\n\t\t\tconst committed = store.commit(record.atom, acceptOptions);\n\t\t\tappendTransition(record, \"committed\", { committed });\n\t\t\treturn committed;\n\t\t},\n\n\t\treject(observationId, owner, reason) {\n\t\t\tassertNonEmptyString(reason, \"reject reason\");\n\t\t\tconst key = keyOf(owner, observationId);\n\t\t\tconst record = records.get(key);\n\t\t\tif (!record) throw new Error(`Unknown observation: ${observationId}`);\n\t\t\tif (record.state === \"committed\") throw new Error(\"A committed memory cannot be rejected\");\n\t\t\tif (record.state === \"rejected\") return record;\n\t\t\treturn appendTransition(record, \"rejected\", { rejectedReason: reason }, reason);\n\t\t},\n\n\t\tstateOf(observationId, owner) {\n\t\t\treturn records.get(keyOf(owner, observationId)) as MemoryCandidateRecordV1 | undefined;\n\t\t},\n\t};\n}\n\nfunction assertNonEmptyString(value: unknown, label: string): asserts value is string {\n\tif (typeof value !== \"string\" || value.trim().length === 0) throw new Error(`${label} must be a non-empty string`);\n}\n\nexport type { MemoryScopeV1 };\n"]}