@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.

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).