@abot-ai/runtime 1.0.0 → 1.1.0

package/dist/src/web-ui/local-runtime/memory-onboarding-routes.d.ts

@@ -0,0 +1,17 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { LongTermMemoryOnboardingService } from "../../runtime/long-term-memory/onboarding/contracts.js";
+type JsonBody = Record<string, unknown> | null;
+export declare class LongTermMemoryOnboardingRoutes {
+    private readonly service;
+    constructor(service: LongTermMemoryOnboardingService);
+    handle(params: {
+        method: string;
+        route: string;
+        url: URL;
+        body: JsonBody;
+        request: IncomingMessage;
+        response: ServerResponse;
+    }): Promise<boolean>;
+    private handleKnownRoute;
+}
+export {};

package/dist/src/web-ui/local-runtime/memory-onboarding-routes.js

@@ -0,0 +1,81 @@
+import { getString, sendJson } from "./http.js";
+import { withHttpRequestAbortSignal } from "./request-abort.js";
+export class LongTermMemoryOnboardingRoutes {
+    service;
+    constructor(service) {
+        this.service = service;
+    }
+    async handle(params) {
+        try {
+            return await this.handleKnownRoute(params);
+        }
+        catch (error) {
+            sendJson(params.response, readErrorStatus(error), {
+                ok: false,
+                error: "long_term_memory_onboarding_failed",
+                message: error instanceof Error ? error.message : String(error),
+            });
+            return true;
+        }
+    }
+    async handleKnownRoute(params) {
+        if (params.method === "GET" && params.route === "runtime/memory") {
+            sendJson(params.response, 200, {
+                ok: true,
+                status: await this.service.status(),
+            });
+            return true;
+        }
+        if (params.method === "GET" &&
+            params.route === "runtime/memory/models") {
+            const providerId = params.url.searchParams.get("provider") ?? "";
+            sendJson(params.response, 200, {
+                ok: true,
+                catalog: await withHttpRequestAbortSignal({
+                    request: params.request,
+                    response: params.response,
+                    reason: "memory_onboarding_discovery_request_aborted",
+                    run: (abortSignal) => this.service.discover({ providerId, abortSignal }),
+                }),
+            });
+            return true;
+        }
+        if (params.method === "POST" &&
+            params.route === "runtime/memory/enable") {
+            const result = await withHttpRequestAbortSignal({
+                request: params.request,
+                response: params.response,
+                reason: "memory_onboarding_enable_request_aborted",
+                run: (abortSignal) => this.service.enable({
+                    providerId: getString(params.body?.providerId),
+                    model: getString(params.body?.model),
+                    ...(getString(params.body?.profileId)
+                        ? { profileId: getString(params.body?.profileId) }
+                        : {}),
+                    emitClientEvents: params.body?.emitClientEvents === true,
+                    abortSignal,
+                }),
+            });
+            sendJson(params.response, 200, { ok: true, ...result });
+            return true;
+        }
+        if (params.method === "POST" &&
+            params.route === "runtime/memory/disable") {
+            sendJson(params.response, 200, {
+                ok: true,
+                ...(await this.service.disable()),
+            });
+            return true;
+        }
+        return false;
+    }
+}
+function readErrorStatus(error) {
+    if (!error || typeof error !== "object" || !("statusCode" in error)) {
+        return 400;
+    }
+    const statusCode = Number(error.statusCode);
+    return Number.isInteger(statusCode) && statusCode >= 400 && statusCode <= 599
+        ? statusCode
+        : 400;
+}

package/dist/src/web-ui/local-runtime/request-abort.d.ts

@@ -0,0 +1,7 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+export declare function withHttpRequestAbortSignal<T>(params: {
+    request: IncomingMessage;
+    response: ServerResponse;
+    reason: string;
+    run: (abortSignal: AbortSignal) => Promise<T>;
+}): Promise<T>;

package/dist/src/web-ui/local-runtime/request-abort.js

@@ -0,0 +1,19 @@
+export async function withHttpRequestAbortSignal(params) {
+    const controller = new AbortController();
+    const abort = () => controller.abort(new Error(params.reason));
+    const abortOnResponseClose = () => {
+        if (!params.response.writableEnded)
+            abort();
+    };
+    params.request.once("aborted", abort);
+    params.response.once("close", abortOnResponseClose);
+    if (params.request.aborted || params.response.destroyed)
+        abort();
+    try {
+        return await params.run(controller.signal);
+    }
+    finally {
+        params.request.removeListener("aborted", abort);
+        params.response.removeListener("close", abortOnResponseClose);
+    }
+}

package/dist/src/web-ui/local-runtime-backend.js

@@ -1,3 +1,4 @@
+import { resolveProviderAdapters } from "../model-gateway/server/index.js";
 import { LocalRuntimeApiRouter } from "./local-runtime/api-router.js";
 import { LocalRuntimeControlRoutes } from "./local-runtime/control-routes.js";
 import { RuntimeEnvironmentRegistry } from "./local-runtime/environment-registry.js";
@@ -12,11 +13,17 @@ export class LocalRuntimeWebBackend {
     realtime;
     controls;
     constructor(options) {
-        this.environments = new RuntimeEnvironmentRegistry(options);
+        const resolvedOptions = {
+            ...options,
+            providerAdapters: resolveProviderAdapters({
+                providerAdapters: options.providerAdapters,
+            }),
+        };
+        this.environments = new RuntimeEnvironmentRegistry(resolvedOptions);
         const clients = new RealtimeClientHub();
         const requests = new LocalRequestExecution(clients);
-        this.api = new LocalRuntimeApiRouter(options, this.environments, requests);
-        this.realtime = new LocalRealtimeController(options, this.environments, requests, clients);
+        this.api = new LocalRuntimeApiRouter(resolvedOptions, this.environments, requests);
+        this.realtime = new LocalRealtimeController(resolvedOptions, this.environments, requests, clients);
         this.controls = new LocalRuntimeControlRoutes(requests);
     }
     async handleHttp(req, res, pathname) {

package/dist/src/web-ui/server.d.ts

@@ -1,3 +1,4 @@
+import type { ModelProviderAdapterRegistry } from "../model-gateway/index.js";
 export type WebUiSetupCommandMode = "source" | "package";
 export type WebUiEnvironmentOption = {
     id: string;
@@ -20,6 +21,7 @@ type WebUiServerOptions = {
     rootDir?: string;
     configPath?: string;
     setupCommandMode?: WebUiSetupCommandMode;
+    providerAdapters?: ModelProviderAdapterRegistry;
 };
 type WebUiServerHandle = {
     close: () => Promise<void>;

package/dist/src/web-ui/server.js

@@ -201,6 +201,9 @@ export function startWebUiServer(overrides = {}) {
             rootDir: options.rootDir,
             configPath: options.configPath,
             defaultEnvironmentId: options.defaultEnvironmentId,
+            ...(options.providerAdapters
+                ? { providerAdapters: options.providerAdapters }
+                : {}),
         })
         : null;
     const externalBridgeBackend = options.backend === "bridge"

package/docs/configuration.md

@@ -85,6 +85,57 @@ and write it automatically to the generated model config:
 Use the same block when configuring an OpenAI model profile manually. Other
 providers are not implicitly assigned this policy by the initializer.
 
+## Passive Long-Term Memory
+
+Passive cross-session memory is opt-in. The default is equivalent to:
+
+```json
+{
+  "longTermMemory": {
+    "enabled": false,
+    "emitClientEvents": false
+  }
+}
+```
+
+Enable it through the shared Web UI or CLI onboarding flow whenever possible:
+
+```bash
+npm run memory -- enable --provider <provider-id> --model <embedding-model-id>
+```
+
+The flow creates a dedicated `models.embeddingProfiles` entry, performs a real
+embedding probe, validates the full config, and then atomically enables
+`longTermMemory`. A manual equivalent is:
+
+```json
+{
+  "models": {
+    "embeddingProfiles": {
+      "memory-embedding": {
+        "provider": "ollama",
+        "model": "<embedding-model-id>"
+      }
+    }
+  },
+  "longTermMemory": {
+    "enabled": true,
+    "emitClientEvents": false,
+    "embeddingProfileId": "memory-embedding"
+  }
+}
+```
+
+The referenced provider must already exist under `models.providers`. Embedding
+profiles accept `provider`, `model`, optional `label`, and optional JSON-safe
+`options`. Generation, reasoning, context-window, and output-budget fields are
+rejected because embedding and response-generation profiles have different
+contracts.
+
+`emitClientEvents` exposes bounded lifecycle status and counts, never memory
+content or vectors. See [Passive Long-Term Memory](long-term-memory.md) for
+storage, privacy, retrieval, and management behavior.
+
 ## Paths
 
 `environment.paths.runtimeDir` is environment-local generated runtime state.
@@ -180,27 +231,20 @@ request-runner config:
 ```
 
 `requestRunner.configRef` is resolved relative to the runtime config file, not
-the process working directory. The referenced file owns the complete set of
-runtime model-step mappings and timeouts plus the request context budget:
+the process working directory. The referenced file owns model-step routing
+overrides, timeout defaults and overrides, and the request context budget.
+Fresh configurations use request-runner schema version 2:
 
 ```json
 {
+  "schemaVersion": 2,
   "models": {
     "defaults": {
       "profileId": "default",
       "steps": {
-        "supervisor.decision": "supervisor.decision",
-        "supervisor.response": "supervisor.response",
-        "planner.decision": "planner.decision",
-        "planner.graph": "planner.graph",
-        "worker.decision": "worker.decision",
-        "worker.result": "supervisor.response",
-        "reviewer.decision": "reviewer.decision",
-        "degraded.finalization": "degraded.finalization",
-        "execution.decision": "execution.decision",
-        "execution.response": "execution.response",
-        "auditor.decision": "auditor.decision",
-        "context.compact": "context.compact",
+        "supervisor.response": "default",
+        "worker.result": "default",
+        "execution.response": "default",
         "tool_payload.raw": "toolPayload.raw"
       }
     }
@@ -210,24 +254,54 @@ runtime model-step mappings and timeouts plus the request context budget:
     "safetyReserveTokens": 1200,
     "attachmentReserveTokens": 1024
   },
+  "stepDefaults": {
+    "timeoutMs": 90000
+  },
   "steps": {
-    "supervisor.decision": { "timeoutMs": 90000 },
-    "supervisor.response": { "timeoutMs": 90000 },
-    "planner.decision": { "timeoutMs": 90000 },
-    "planner.graph": { "timeoutMs": 90000 },
-    "worker.decision": { "timeoutMs": 90000 },
-    "worker.result": { "timeoutMs": 90000 },
-    "reviewer.decision": { "timeoutMs": 90000 },
-    "degraded.finalization": { "timeoutMs": 90000 },
-    "execution.decision": { "timeoutMs": 90000 },
-    "execution.response": { "timeoutMs": 90000 },
-    "auditor.decision": { "timeoutMs": 90000 },
-    "context.compact": { "timeoutMs": 90000 },
-    "tool_payload.raw": { "timeoutMs": 90000 }
+    "supervisor.response": {
+      "instructionRefs": [
+        "../methodologies/response-ux.md",
+        "../methodologies/memory-informed-response.md"
+      ]
+    },
+    "execution.response": {
+      "instructionRefs": [
+        "../methodologies/response-ux.md",
+        "../methodologies/memory-informed-response.md"
+      ]
+    }
   }
 }
 ```
 
+In schema version 2, `models.defaults.steps` is a sparse override map. A
+missing model-step mapping resolves to the same id as the step, so an identity
+entry such as `"capability.controls": "capability.controls"` is unnecessary.
+The four entries above are the canonical non-identity overrides: three raw
+response steps use the base `default` profile, while `tool_payload.raw` uses
+the existing `toolPayload.raw` calibration slot. An explicit target may still
+select a model profile, invocation profile, or calibration slot; an unknown
+explicit target is rejected rather than replaced with a default.
+
+`stepDefaults.timeoutMs` supplies the timeout for every step. The root `steps`
+object is also sparse: add `timeoutMs` only when a step differs from the
+default, and add `instructionRefs` only when that step needs additional
+instructions. A missing step entry therefore uses the default timeout and has
+no additional instruction references.
+
+A request-runner config with no `schemaVersion` is the legacy v1 format
+published with ABot 1.0.0. It remains supported and is normalized in memory;
+the loader does not rewrite it, and adding a runtime model step does not require
+the user to add a new identity mapping. `schemaVersion: 2` is the only explicit
+supported version. Any other explicit value is rejected before the config is
+used or written.
+
+A fresh `abot init` creates schema version 2. Running init against an existing
+project without `--force` preserves its request-runner config byte for byte,
+including a legacy v1 file. Package upgrades never run a config migration or
+rewrite automatically; `--force` remains an explicit request to replace the
+local starter files.
+
 Every materialized model profile declares its physical context capacity with
 top-level `contextWindowTokens`. The selected profile supplies that capacity;
 the request-runner context block supplies only admission headroom.
@@ -241,16 +315,23 @@ The Ollama adapter still sends a finite provider-native `num_predict`, derived
 mechanically from the final provider input, the physical context remainder,
 and a strict bounded output schema when one applies.
 
-All three root fields and every invoked step are required. Unknown fields,
-missing steps, and extra step ids are rejected during configuration loading.
-`worker.result` is a raw-text authoring step. It may reuse a model profile's
-existing raw-response calibration slot, as shown above, without changing its
-distinct runtime identity.
+The required context fields remain explicit. Unknown fields, unknown step ids,
+and invalid explicit overrides are rejected during configuration loading;
+omitting a mapping or step entry uses the schema version 2 defaults described
+above. `instructionRefs` are resolved relative to the request-runner config.
+The `abot init` command installs the two default root-response methodologies
+beside the local configuration, and the same references are applied to
+`supervisor.response` and `execution.response`. They are presentation guidance
+only and cannot alter the available actions, output contract, or runtime
+authority.
+`worker.result` is a raw-text authoring step. The canonical override selects the
+base `default` profile without changing the step's distinct runtime identity;
+an installation may still configure a more specific explicit target.
 `planner.decision` remains the delegated MAIN Planner contract and keeps its
 configured methodology references. `planner.graph` is the separate structured
 graph proposal/decline contract used by the Execution Agent advisory Planner;
-it has its own mapping, timeout, output contract, and model calibration and does
-not inherit `planner.decision` instruction references.
+it receives its own normalized mapping, timeout, output contract, and model
+calibration and does not inherit `planner.decision` instruction references.
 The request runner has no configurable role hierarchy or fixed sequence. A
 model profile may select one code-owned execution policy; omission uses the
 current Supervisor/Worker behavior:
@@ -374,15 +455,15 @@ loss before a checkpoint covers those turns.
 supported. Tool observations and artifact context are projected by their
 owning runtime contracts; model profiles cannot override those boundaries.
 
-The request-runner config maps internal `modelStep` ids to semantic calibration
-slot ids:
+The request-runner config maps internal `modelStep` ids only when a target
+differs from the schema version 2 identity default:
 
 ```json
 {
   "models": {
     "defaults": {
       "steps": {
-        "supervisor.decision": "supervisor.decision"
+        "tool_payload.raw": "toolPayload.raw"
       }
     }
   }
@@ -428,12 +509,13 @@ Use this bounded workflow:
 
 The common slots and their first tuning targets are:
 
-| Step family                     | Slots                                                                                                                                                                 | Tune first                                                                                                                                                                 |
-| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Step family                     | Slots                                                                                                                                                                 | Tune first                                                                                                                                                                              |
+| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | Routing and decisions           | `supervisor.decision`, `worker.decision`, `planner.decision`, `planner.graph`, `reviewer.decision`, `execution.decision`, `auditor.decision`, `degraded.finalization` | Keep the required structured `format`, then verify complete structured output and deterministic sampling. Add short model-specific instructions only when measured behavior needs them. |
-| User-facing or delegated output | `supervisor.response`, `worker.result`, `execution.response`                                                                                                          | Sampling and any intentional provider-native output controls. Do not force JSON unless that step's contract requires it.                                                    |
-| Context compaction              | `context.compact`                                                                                                                                                     | Structured format and preservation of facts that later steps still require; physical capacity remains profile-owned.                                                       |
-| Literal tool payloads           | `toolPayload.raw`                                                                                                                                                     | Literal-payload instructions and any intentional provider-native output controls. Verify the produced payload or artifact directly, not the model's description of it.     |
+| Capability control authoring    | `capability.controls`                                                                                                                                                 | Preserve the structured controls contract without applying the short decision-output ceiling.                                                                                           |
+| User-facing or delegated output | `supervisor.response`, `worker.result`, `execution.response`                                                                                                          | Sampling and any intentional provider-native output controls. Do not force JSON unless that step's contract requires it.                                                                |
+| Context compaction              | `context.compact`                                                                                                                                                     | Structured format and preservation of facts that later steps still require; physical capacity remains profile-owned.                                                                    |
+| Literal tool payloads           | `toolPayload.raw`                                                                                                                                                     | Literal-payload instructions and any intentional provider-native output controls. Verify the produced payload or artifact directly, not the model's description of it.                  |
 
 `timeoutMs` addresses provider latency only; raising it does not improve model
 reasoning. Top-level `contextWindowTokens` declares the concrete model
@@ -443,9 +525,10 @@ but a provider may intentionally omit unsupported sampling fields, such as
 temperature for an enabled OpenAI reasoning mode.
 
 An omitted slot inherits the model profile's base generation and context. The
-packaged request-runner example already maps each semantic step to its matching
-calibration slot, so most users only need to edit the profile file for the
-model they are tuning.
+packaged schema version 2 request-runner example lists only the four canonical
+non-identity overrides; all other steps resolve to their matching calibration
+slot automatically. Most users therefore only need to edit the profile file
+for the model they are tuning.
 
 ## Schema
 

package/docs/installation.md

@@ -91,6 +91,24 @@ npx abot add-model --profile <profile-id> --provider openai --model <model-id>
 Add `--default` only to select that profile as the default. It does not delete
 the profiles that are already configured.
 
+### Optional Passive Long-Term Memory
+
+Long-term memory is disabled by default. After a provider is configured, choose
+an embedding model and enable it through the Web UI Config workspace or CLI:
+
+```bash
+npx abot memory status
+npx abot memory models --provider <provider-id>
+npx abot memory enable --provider <provider-id> --model <embedding-model-id>
+```
+
+ABot does not install or choose the embedding model. The enable command performs
+a real probe, writes config only after it succeeds, and reports that the Runtime
+must be restarted. OpenAI users enter the embedding model id manually; Ollama
+users can discover model ids installed at the configured Ollama endpoint.
+
+See [Passive Long-Term Memory](long-term-memory.md) before enabling persistence.
+
 ## Use As A Library
 
 After the package is published:
@@ -134,6 +152,9 @@ The package includes the public plugin catalog. Additional consumer plugins may
 be installed under `<consumer-root>/plugins`. A consumer plugin cannot replace
 a bundled plugin: duplicate plugin ids fail closed.
 
+The passive long-term memory service belongs to the Runtime core and does not
+depend on the bundled `memory` plugin.
+
 Web URL fetching is available through the bundled Web plugin without a search
 credential. Set `BRAVE_SEARCH_API_KEY` to make `web_search` operational. With
 no key, `web_fetch` remains operational and a `web_search` invocation fails

package/docs/known-limitations.md

@@ -61,6 +61,17 @@ plugin entrypoints are not currently supported.
 Plugin behavior belongs inside the plugin. Runtime orchestration should only
 see the generic selected catalog and execution results.
 
+## Passive Long-Term Memory
+
+Passive long-term memory is disabled by default and requires an embedding model
+selected and operated by the consumer. ABot provides OpenAI and Ollama adapter
+contracts, but it does not install, download, or choose that model.
+
+Ollama exposes installed-model discovery. OpenAI does not expose equivalent
+discovery through this integration, so its embedding model id is entered
+manually. If an enabled embedding provider becomes unavailable, memory
+retrieval or saving is skipped while the completed user response is preserved.
+
 ## Web UI
 
 The packaged Web UI is the primary local GUI. Its default backend talks directly

package/docs/long-term-memory.md

@@ -0,0 +1,181 @@
+# Passive Long-Term Memory
+
+ABot Runtime can retain selected user facts and preferences across sessions.
+This feature is passive: the model does not invoke a memory tool, and the
+Runtime core remains the only owner of retrieval, filtering, deduplication,
+storage, and deletion.
+
+Long-term memory is disabled by default. Enabling it is an explicit consumer
+choice because it may persist personal information between conversations.
+
+## How It Works
+
+The Supervisor path separates memory proposal from the user-facing response.
+When long-term memory is enabled, `supervisor.response` first performs one
+structured candidate-only call:
+
+```json
+{
+  "memoryCandidates": [
+    {
+      "content": "A durable fact or preference established by the user.",
+      "tags": ["normalized-later-by-core"]
+    }
+  ]
+}
+```
+
+`memoryCandidates` is empty when there is nothing durable to propose. The
+Supervisor then authors the complete user-facing response through its ordinary
+raw-text contract, without a JSON wrapper. Invalid or unavailable candidate
+authoring is isolated to an empty candidate list and cannot replace or
+invalidate that raw response. This sequential split adds the candidate-call
+latency before the Supervisor response is delivered.
+
+`execution.response` retains the combined strict envelope containing both
+`finalResponse` and `memoryCandidates`; its external response contract is
+unchanged.
+
+Candidate data remains internal and is processed after the final assistant
+response is persisted. Persistence runs through a Runtime-owned background
+queue; response completion never waits for embedding or memory-store work.
+
+Before the next terminal response is authored, the Runtime retrieves a small
+relevant set from the cross-session pool. Retrieval uses provider embeddings
+plus bounded lexical, tag, and recency scoring. The projection is passive
+reference context; it is never treated as a new user request or an instruction.
+
+Retrieval, candidate policy, filtering, deduplication, and persistence are
+shared by `supervisor.response` and `execution.response`; only their authoring
+contracts differ. Decision, planning, Worker, Reviewer, payload, and tool
+contexts do not receive the long-term memory projection.
+
+Both response paths also share the same configured response-experience
+methodology. It applies whether memory is enabled or disabled. Relevant memory
+is an optional passive layer that may improve continuity and useful defaults;
+it never replaces the current request, forces a personal reference, or grants
+action authority.
+
+## Enable It
+
+Configure an ordinary model provider first with `abot init` or `abot add-model`.
+Then choose an embedding model exposed by that provider. ABot does not choose,
+install, or download an embedding model.
+
+For a packaged installation:
+
+```bash
+npx abot memory status
+npx abot memory models --provider <provider-id>
+npx abot memory enable --provider <provider-id> --model <embedding-model-id>
+```
+
+From a source checkout, use the equivalent commands:
+
+```bash
+npm run memory -- status
+npm run memory -- models --provider <provider-id>
+npm run memory -- enable --provider <provider-id> --model <embedding-model-id>
+```
+
+Add `--emit-events` to expose bounded lifecycle events to clients. Enablement
+performs a real embedding probe and validates the complete candidate config
+before writing it. The previous config is backed up, and a restart is required
+after enablement or disablement.
+
+The Config workspace in the packaged Web UI uses the same onboarding service.
+It can list configured providers, discover models when the provider supports
+discovery, probe and enable a selected model, or disable the feature. A provider
+without discovery support accepts a model id entered by the user.
+
+## Configuration Contract
+
+The onboarding flow writes a dedicated embedding profile and binds the feature
+to it:
+
+```json
+{
+  "models": {
+    "embeddingProfiles": {
+      "memory-embedding": {
+        "label": "Long-term memory embeddings",
+        "provider": "ollama",
+        "model": "<embedding-model-id>"
+      }
+    }
+  },
+  "longTermMemory": {
+    "enabled": true,
+    "emitClientEvents": false,
+    "embeddingProfileId": "memory-embedding"
+  }
+}
+```
+
+Embedding profiles are intentionally separate from generation profiles. They
+accept `provider`, `model`, optional `label`, and provider-owned JSON-safe
+`options`; generation, reasoning, context-window, and output settings are not
+valid embedding-profile fields.
+
+When disabled, no repository read, embedding request, model-output envelope,
+or memory lifecycle event is added to the response path.
+
+## Providers
+
+- Ollama uses its `/api/embed` contract and can discover locally installed
+  model ids through `/api/tags`.
+- OpenAI uses `/embeddings`. Model discovery is not exposed by that provider,
+  so the consumer supplies the embedding model id.
+- A custom model-gateway adapter may implement `embed` and optional
+  `listEmbeddingModels` without changing Runtime memory policy.
+
+If the selected embedding provider becomes unavailable during a request, the
+Runtime skips memory retrieval or persistence, records a bounded diagnostic,
+and preserves normal response delivery.
+
+## Storage, Privacy, And Management
+
+The default adapter stores canonical records and their derived vector index at:
+
+```text
+<runtimeDir>/long-term-memory/memory.json
+```
+
+The file is runtime-generated local state and must not be published or
+committed. Canonical records contain content, normalized tags, timestamps, and
+source session/request provenance. Derived vectors are versioned by model
+fingerprint and are rebuilt when that fingerprint or vector dimension changes.
+
+The core rejects obvious secrets such as private keys, labeled passwords, API
+keys, and common token formats. Exact duplicates are merged mechanically;
+semantic similarity alone never overwrites an existing record.
+
+Library hosts can manage the pool through the composed service:
+
+```ts
+const runtime = createRuntimeApplication(config);
+
+await runtime.services.longTermMemory.status();
+await runtime.services.longTermMemory.list({ limit: 50 });
+await runtime.services.longTermMemory.delete({ id: memoryId });
+await runtime.services.longTermMemory.clear();
+```
+
+Management APIs return canonical records, not embedding vectors.
+
+## Client Events
+
+With `emitClientEvents: true`, clients may receive bounded lifecycle events:
+
+- `memory.retrieval.started|completed|failed`
+- `memory.save.queued`
+
+The save event confirms only that background persistence was scheduled. Its
+completion or failure is diagnostic-only and cannot change the completed user
+response. Client events contain lifecycle status and counts only. They never
+include memory content, tags, vectors, credentials, or the model's internal
+candidates.
+
+The bundled `memory` plugin remains a separate, explicit user-invoked
+capability. Passive long-term memory does not depend on that plugin and remains
+operational if the plugin is disabled or removed.