@agent-forge/plugin-memory

First-party memory capability plugin for Agent Forge: the memory_write / memory_recall / memory_list / memory_forget / memory_enable model face over the M5 Memory Foundation, extracted from the host's embedded builtin capability (D-075 S4, fourth batch).

Library face vs plugin entry

• createMemoryCapability(api, context, override?) — explicit-context factory for embedders and tests. The agent dir, resolved mode, lessons setting, storage components, and the test-only vector override are injected explicitly.
• createCapabilityWithVectorComponents(api, context, override) — test-only harness over the capability (registration list plus vector/enabling state hooks), for the deterministic mock gate.
• ./dist/entry.js (default export) — the manifest-loaded plugin factory. It maps host services onto the same context:
  • api.host.agentDir → ledger root <agentDir>/memory/ + the agent-dir config channel <agentDir>/capabilities/builtin.memory.json
  • api.host.memoryStorage → the A1/A2 storage injection face (MemoryStorageComponentsV1); absent = built-in local implementation
  • 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 → 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)

Config channel: hosts declaring api.host.agentDir get <agentDir>/capabilities/builtin.memory.json merged over the manifest config (missing file = unconfigured; unreadable/invalid JSON fails the plugin load).

Bundled modules

The 29 Foundation/semantic modules (canonical atom + store + durable ledger, candidate machine, lifecycle, scheduler + scheduler-api facade, curation, continuation, recall agent/index/packet, egress policy, memory network, preference resolver/disambiguator/lifecycle/promotion, purge gate/journal, suite-memory facade, transfer + upcasters, vector index, embedding provider/reranker, write budget, code-memory, assistant preference card) and the deterministic memory testkit live in this package and are re-exported from the index. The memory public contracts (canonical atom family, store/ledger/vector seams, MemoryStorageComponentsV1, MEMORY_RECALL_TOOL_NAME) come from @agent-forge/plugin-sdk.

Heavy runtime dependencies stay lazy: @lancedb/lancedb and @huggingface/transformers load via dynamic import() only inside the vector-channel enabling path — the default light mode (vector channel stays disabled until memory_enable consent), mode off, and the pure store/ledger paths never touch them.

本地装配失败和插件卸载会释放本实例的模型与索引。已进入的原生推理先完成再释放； 清理错逐资源保留原始错误并输出 stderr，不调用宿主已经撤销的插件 API； 某一资源或诊断输出失败不会阻断其他资源释放。 transformers 4.3.0 尚不提供逐调用下载取消，卸载后只阻止新推理与后续重试， 晚到加载会释放而不会发布通道。共享推理服务的模型由服务进程持有，会话卸载只断开客户端。 成功缓存不删除，非空权重和手工导入文件保持原有检查契约。 真实验收先经公开 memory_enable({action:"download"}) 单独准备资源，随后用同一测试私有 agentDir 验证跨会话写入与召回；冷资源耗时不计入模型任务时限，也不宣称因此变快。 真实 fixture 同时按生产流程物化安装副本的依赖；失败时保留私有目录与 sidecar 日志。 详见 docs/design/冷资源准备与取消边界.md。

Identity

Plugin manifest id agent-forge.plugin.memory; the embedded capability manifest id agent-forge.builtin.memory is retained as the owner string for durable facts (ledger write reasons, purge authorization refs) so existing on-disk state keeps resolving.

Capabilities

Requires session + events + tools. Provides the memory.scheduler service (v1).