@ai-agent-forge/plugin-memory 0.88.1 → 0.88.3

package/README.md

@@ -23,10 +23,16 @@ capability (D-075 S4, fourth batch).
   - mode resolution reuses `resolveMemoryMode`: config `memoryMode` (host
     configOverride wiring lands with the host cutover batch) → env
     `AGENT_FORGE_MEMORY_MODE` (read in the entry) → config
-    `memorySettingsMode` → legacy alias → off
-  - a resolved mode of `off`, or a host without `agentDir`, registers nothing
-    (one debug log line; the factory never throws for a disabled
-    configuration)
+    `memorySettingsMode` → legacy alias → light (the factory default since
+    the 2026-10-05 flip; invalid values fail closed to `off`)
+  - a resolved mode of `off`, a persisted consent decline
+    (`memoryConsent: "declined"` in the agent-dir config suppressing the
+    default tier), or a host without `agentDir` registers nothing (one debug
+    log line; the factory never throws for a disabled configuration)
+  - the model download runs in the background (host preheat via
+    `memory_enable`); `memoryConsent` and the persisted
+    `memorySettingsMode` preset live in the agent-dir config channel and are
+    written by the `/memory` command face
   - `vectorComponents` does NOT ride the entry — it is the library/test face
     only (deterministic mock gate)
 

package/agent-forge.json

@@ -1,7 +1,7 @@
 {
 	"packageFormatVersion": 1,
 	"id": "agent-forge.plugin.memory",
-	"pluginVersion": "0.88.1",
+	"pluginVersion": "0.88.3",
 	"apiVersion": "1",
 	"minHostVersion": "0.84.4",
 	"platform": {

package/bin/agent-forge-memory-inference.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+/**
+ * npm bin wrapper for the memory inference service process entry (Slice B1).
+ * The spawn path used in-process is `node <plugin>/bin/agent-forge-memory-inference.js`
+ * (portable across platforms, no npm shim reliance); this file also registers
+ * the command for npm consumers. It only re-exports the real entry in dist.
+ */
+import "../dist/inference-bin.js";

package/dist/capability.d.ts

@@ -1,6 +1,13 @@
 import type { MemoryCapabilityOverrideV1, MemoryModeV1, MemoryStorageComponentsV1 } from "@agent-forge/plugin-sdk";
 import { type CapabilityAPI, type DisposableRegistration } from "@agent-forge/plugin-sdk";
 export { MEMORY_RECALL_TOOL_NAME, type MemoryCapabilityOverrideV1, type MemoryEnablingOverrideV1, type MemoryModeV1, type MemoryStorageComponentsV1, type MemoryVectorComponentsOverrideV1, } from "@agent-forge/plugin-sdk";
+export { MEMORY_AGENT_DIR_CONFIG_RELATIVE_PATH, MEMORY_CONSENT_DECLINED_VALUE, writeMemoryConsentDeclined, writeMemorySettingsMode, } from "./memory/enabling.ts";
+export { MEMORY_AUTO_RECALL_DEADLINE_MS, MEMORY_AUTO_RECALL_DISCLAIMER, MEMORY_AUTO_RECALL_MARKER, type MemoryLessonsResolutionV1, type MemoryLessonsSettingV1, resolveMemoryLessons, } from "./memory/hooks.ts";
+export { MEMORY_TOOLS_GUIDE } from "./memory/recall-pipeline.ts";
+export { type MemoryCapabilityStateV1, type MemoryConsentNeededV1, type MemoryEnablingFailureV1, VECTOR_DB_DIRNAME, VECTOR_MODEL_CACHE_DIRNAME, VECTOR_RERANKER_MODEL_ID, } from "./memory/vector-channel.ts";
+export { MEMORY_TIER_UPGRADE_STORE_THRESHOLD } from "./memory/write-face.ts";
+import { type MemoryLessonsSettingV1 } from "./memory/hooks.ts";
+import type { MemoryCapabilityStateV1, MemoryEnablingFailureV1 } from "./memory/vector-channel.ts";
 export declare const capabilityManifest: {
     readonly id: "agent-forge.builtin.memory";
     readonly version: "0.1.0";
@@ -12,31 +19,6 @@ export declare const capabilityManifest: {
         readonly kind: "service";
     }];
 };
-/**
- * Marker text of the auto-recall injection message (B1 记忆自动注入, D-071 增补
- * 裁决自 sdk 迁入; pinned by test/memory-sdk-e2e.test.ts).
- */
-export declare const MEMORY_AUTO_RECALL_MARKER = "<auto_recalled_memory>";
-/**
- * Tail line of every auto-recall injection block (错误教训与召回质量护栏设计
- * §2.1): tells the model the block was recalled rather than written by the
- * user and may be outdated. Pinned verbatim by test/memory-error-lessons.test.ts.
- */
-export declare const MEMORY_AUTO_RECALL_DISCLAIMER = "(Recalled automatically from persistent memory for this request \u2014 not written by the user. Recalled items may be outdated; verify against current state before relying on them.)";
-/**
- * Memory tools guide（记忆 runtime 注入面，原 system-prompt.ts MEMORY_TOOL_GUIDE，
- * D-071 迁移）：the model-facing hint that the persistent memory tools exist.
- * It rides memory_recall's promptGuidelines so the text lives with the plugin
- * that owns the tools (宪法 §3) and renders whenever the tool face is active.
- */
-export declare const MEMORY_TOOLS_GUIDE = "Memory: You have persistent memory tools (memory_write, memory_recall, memory_list, memory_forget). Use memory_recall to look up user preferences or project facts before answering. Use memory_write to save important decisions, preferences, or findings for future sessions.";
-/**
- * Owner (isolation principal) of every atom this capability writes. The
- * Foundation owner is the store/facade isolation identity; this product ships
- * one local user per agentDir, so one stable owner id partitions the ledger
- * directory `<agentDir>/memory/<owner>/ledger-<suiteId|"legacy">.jsonl`.
- */
-export declare const BUILTIN_MEMORY_OWNER = "local-user";
 /**
  * 解析后的全局模式 (2.4d6 S1)。`invalidEnvValue` 非空 = 配置的环境值非法,
  * 已 fail-closed 回 off, 调用方负责以此输出一次 warn; `invalidSettingsValue`
@@ -54,28 +36,13 @@ export interface MemoryModeResolutionV1 {
 /**
  * memory.mode 解析 (2.4d6 S1)。优先级: context 显式值 → 环境变量
  * `AGENT_FORGE_MEMORY_MODE` → settings.json `memory.mode` (settingsMode 参, 持
- * 久配置面) → 旧别名 `AGENT_FORGE_MEMORY_VECTOR` (兼容期) → 默认 off。env 是
+ * 久配置面) → 旧别名 `AGENT_FORGE_MEMORY_VECTOR` (兼容期) → 默认 light
+ * (2026-10-05 用户裁决翻转默认 off→light, 对齐主流编程助手开箱即用方向)。env 是
  * 临时覆盖、settings 是持久配置 (env > 文件, 沿用本仓 suite 解析先例)。任何
  * 非法配置值 fail-closed 为 off 并在结果中携带原值供调用方告警一次, 绝不静默
  * 改档或意外下载。
  */
 export declare function resolveMemoryMode(explicitMode: string | undefined, env?: Readonly<Record<string, string | undefined>>, settingsMode?: string): MemoryModeResolutionV1;
-/** bash 失败教训捕获开关取值 (§2.2)。 */
-export type MemoryLessonsSettingV1 = "on" | "off";
-/**
- * lessons 开关解析结果: `invalidEnvValue` 非空 = 配置值非法, 已 fail 回默认 on,
- * 调用方负责以此告警一次。
- */
-export interface MemoryLessonsResolutionV1 {
-    readonly lessons: MemoryLessonsSettingV1;
-    readonly invalidEnvValue?: string;
-}
-/**
- * context.memory.lessons 解析 (§2.2, resolveMemoryMode 同构): 显式值 → 环境变量
- * `AGENT_FORGE_MEMORY_LESSONS` → 默认 on。任何非法配置值回默认并在结果中携带
- * 原值供调用方告警一次, 绝不静默改开关。
- */
-export declare function resolveMemoryLessons(explicitLessons: string | undefined, env?: Readonly<Record<string, string | undefined>>): MemoryLessonsResolutionV1;
 /** Host-provided factory context; provided by the host session assembly (sdk suite membership). */
 export interface MemoryCapabilityContext {
     /** Agent home directory — roots the durable ledger under `<agentDir>/memory/`. */
@@ -116,6 +83,22 @@ export interface MemoryCapabilityContext {
      * 的第三参语义一致, 第三参优先。
      */
     readonly vectorComponents?: MemoryCapabilityOverrideV1;
+    /**
+     * 共享推理服务装配缝 (Slice B2, 记忆共享推理服务设计 §3.1/§3.3/§3.6)。
+     * 缺省 (生产) = 真实路径: 模型在位时装配经 TCP loopback 走常驻服务,
+     * 连不上则懒 spawn 插件 bin (`agent-forge-memory-inference`), 重连失败按
+     * enabling failed 呈现 (裁决 A: 不回退本地装配)。测试注入替换对应环节
+     * (deterministic 门禁): `port` 直连测试服务、`spawnImpl` 替换进程拉起、
+     * `modelsInPlace` 声明模型在位 (跳过文件检查, 免写假权重文件)。
+     * loadImpl enabling 缝与 vectorComponents 注入仍走本地装配路径 (既有语义)。
+     */
+    readonly inferenceService?: {
+        readonly port?: number;
+        readonly spawnImpl?: (agentDir: string, mode: "light" | "full", port: number, 
+        /** spawn 异步失败 (EACCES/ENOMEM 等) 的回调; 缺省实现经 child 'error' 事件馈入。 */
+        onError?: (error: Error) => void) => Promise<void>;
+        readonly modelsInPlace?: boolean;
+    };
     /**
      * 记忆底层组件注入 (扩展位盘点 A1/A2 的宿主装配通道): store/ledger 工厂与
      * 向量组件公共契约, 缺省成员走内置默认实现。装配方经
@@ -123,25 +106,19 @@ export interface MemoryCapabilityContext {
      */
     readonly storage?: MemoryStorageComponentsV1;
 }
-/** capability 级状态机 (设计 §3.2): off 只出现在模式关闭 (零注册, 不可观测)。 */
-export type MemoryCapabilityStateV1 = "enabling" | "ready" | "degraded" | "failed";
-/** enabling 失败的结构化结果: 原因 + 行动清单 (硬性要求, 设计 §3.2)。 */
-export interface MemoryEnablingFailureV1 {
-    readonly reason: string;
-    readonly actions: readonly string[];
-}
 /**
- * 本地检查 1b: 重依赖供给 (设计 §3.2 checking)。`@lancedb/lancedb` 与
- * `@huggingface/transformers` 逐个判定 — entries 提供宿主入口路径 = 可用
- * (不触自解析); 未提供时 resolveModule 自解析成功 = 可用, 抛错 = 计入缺失。
- * 返回缺失 specifier 列表 (空 = 通过)。纯函数零 IO; 导出仅供测试 (与宿主侧
- * buildHostDependencyAliases 同一模式), 生产接线传插件位置自解析 — 把加载步
- * 的 "Cannot find module" 泛化包装前置成精准缺供文案, 省掉模型下载等前置工作。
+ * 默认档判定 (征询拒绝只抑制默认档): 显式值、env、settings、旧别名四层全部
+ * 未定档时, 模式来自出厂默认档 (light)。与 resolveMemoryMode 的优先级链同构,
+ * 不改 resolver 返回面。
+ */
+export declare function memoryModeSourceIsDefault(explicitMode: string | undefined, env: Readonly<Record<string, string | undefined>>, settingsMode?: string): boolean;
+/**
+ * Owner (isolation principal) of every atom this capability writes. The
+ * Foundation owner is the store/facade isolation identity; this product ships
+ * one local user per agentDir, so one stable owner id partitions the ledger
+ * directory `<agentDir>/memory/<owner>/ledger-<suiteId|"legacy">.jsonl`.
  */
-export declare function missingHeavyDependencyModules(entries: {
-    lancedb?: string;
-    transformers?: string;
-}, resolveModule: (specifier: string) => string): string[];
+export declare const BUILTIN_MEMORY_OWNER = "local-user";
 /**
  * Creates the builtin memory capability: four tools (memory_write,
  * memory_recall, memory_list, memory_forget) over a per-session Foundation
@@ -171,6 +148,12 @@ export interface MemoryVectorCapabilityHarnessV1 {
      * components): ready, or the structured failure (reason + action list).
      */
     enablingOutcome(): Promise<"ready" | MemoryEnablingFailureV1>;
+    /**
+     * 释放共享推理服务连接 (服务路径) 或本地向量索引 (本地装配路径)。幂等: 引用
+     * 清空后二次调用为 no-op。同名注册项挂 registrations 首位——宿主反向逐个
+     * dispose 时它最后执行 (先拆消费者、后关通道)。
+     */
+    teardown(): void;
 }
 /**
  * Test-only assembly variant: the capability with an injected override (full