@abot-ai/runtime 1.8.1 → 2.0.0

package/dist/src/web-ui/local-runtime/setup-embedding-provider.js

@@ -1,3 +1,4 @@
+import { planNewLlamaEmbeddingProvider, commitLlamaEmbeddingProvider, } from "./setup-embedding-llamacpp.js";
 import { buildProviderConfig } from "../../../scripts/runtime-setup-files.js";
 import { createFileLongTermMemoryOnboardingConfigRepository } from "../../runtime/adapters/long-term-memory/onboarding-config-repository.js";
 import { isRecord } from "../../runtime/config/utils.js";
@@ -57,8 +58,10 @@ function requirePreservedProviderSettings(provider, input) {
     if (input.baseUrl && input.baseUrl !== provider.baseUrl) {
         throw new RuntimeSetupError("embedding_provider_conflict", "That provider already uses another address. Choose its saved connection or edit it in Settings.", 409);
     }
-    if (input.apiKey && provider.type !== "openai") {
-        throw new RuntimeSetupError("invalid_embedding_credential", "Only an OpenAI connection accepts an API key here.");
+    if (input.apiKey &&
+        provider.type !== "openai" &&
+        provider.type !== "llamacpp") {
+        throw new RuntimeSetupError("invalid_embedding_credential", "This connection does not support an API key.");
     }
 }
 /** Adds only the requested provider; chat profiles and existing provider settings stay intact. */
@@ -66,14 +69,19 @@ export async function prepareSetupEmbeddingProvider(options, input) {
     const repository = createFileLongTermMemoryOnboardingConfigRepository(options);
     const snapshot = await repository.read();
     const providers = readProviderMap(snapshot.config.models);
-    const providerId = resolveSetupEmbeddingProviderId(providers, input);
+    const llamaConnection = input.provider === "llamacpp"
+        ? planNewLlamaEmbeddingProvider(providers, input)
+        : undefined;
+    const providerId = llamaConnection?.providerId ??
+        resolveSetupEmbeddingProviderId(providers, input);
     const existing = providers[providerId];
     if (input.providerId && !isRecord(existing)) {
-        throw new RuntimeSetupError("embedding_provider_not_configured", "Choose a configured provider or add an OpenAI or Ollama connection.", 404);
+        throw new RuntimeSetupError("embedding_provider_not_configured", "Choose a configured provider or add an OpenAI, Ollama or llama.cpp connection.", 404);
     }
-    const provider = isRecord(existing)
-        ? existing
-        : buildProviderConfig(input.provider, input.baseUrl);
+    const provider = llamaConnection?.provider ??
+        (isRecord(existing)
+            ? existing
+            : buildProviderConfig(input.provider, input.baseUrl));
     const isolatedCredential = needsIsolatedEmbeddingCredential(existing, input, providerId);
     if (isolatedCredential)
         provider.apiKeyEnv = resolveIsolatedEmbeddingCredentialName(providers, providerId);
@@ -105,8 +113,14 @@ export async function prepareSetupEmbeddingProvider(options, input) {
             preserveExistingCredential: true,
         });
     }
-    if (!isRecord(existing))
-        await repository.write(candidate, snapshot.config);
+    const persistProvider = async () => {
+        if (!isRecord(existing))
+            await repository.write(candidate, snapshot.config);
+    };
+    if (provider.type === "llamacpp")
+        await commitLlamaEmbeddingProvider({ rootDir: options.rootDir, configPath: snapshot.path }, provider, input, persistProvider);
+    else
+        await persistProvider();
     return {
         providerId,
         savedProvider: { id: providerId, type: provider.type },

package/dist/src/web-ui/local-runtime/setup-embedding-routes.d.ts

@@ -1,8 +1,12 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
-import { SetupEmbeddingService } from "./setup-embedding-service.js";
+import type { LongTermMemoryOnboardingResult } from "../../runtime/long-term-memory/onboarding/contracts.js";
+type EmbeddingConnectionService = {
+    enable(body: Record<string, unknown>, signal: AbortSignal): Promise<Pick<LongTermMemoryOnboardingResult, "status" | "probe" | "restartRequired">>;
+};
 export declare class SetupEmbeddingRoutes {
     private readonly service;
-    constructor(service: SetupEmbeddingService);
+    private readonly route;
+    constructor(service: EmbeddingConnectionService, route?: string);
     handle(params: {
         method: string;
         route: string;
@@ -10,3 +14,4 @@ export declare class SetupEmbeddingRoutes {
         response: ServerResponse;
     }): Promise<boolean>;
 }
+export {};

package/dist/src/web-ui/local-runtime/setup-embedding-routes.js

@@ -2,14 +2,16 @@ import { assertConfigMutationRequest, ConfigMutationRequestError, } from "./conf
 import { readBody, readJsonBody, sendJson } from "./http.js";
 import { withHttpRequestAbortSignal } from "./request-abort.js";
 import { RuntimeSetupError } from "./runtime-setup-input.js";
-import { SetupEmbeddingFailure, } from "./setup-embedding-service.js";
+import { SetupEmbeddingFailure } from "./setup-embedding-service.js";
 export class SetupEmbeddingRoutes {
     service;
-    constructor(service) {
+    route;
+    constructor(service, route = "runtime/setup/embedding") {
         this.service = service;
+        this.route = route;
     }
     async handle(params) {
-        if (params.route !== "runtime/setup/embedding")
+        if (params.route !== this.route)
             return false;
         params.response.setHeader("cache-control", "no-store");
         try {

package/dist/src/web-ui/local-runtime/setup-embedding-service.d.ts

@@ -22,6 +22,7 @@ export declare class SetupEmbeddingService {
             providerId?: string;
             model?: string;
             providers: readonly import("../../runtime/index.js").LongTermMemoryOnboardingProvider[];
+            embeddingProfiles: readonly import("../../runtime/index.js").SavedMemoryEmbeddingProfile[];
         }>;
         probe: Readonly<{
             modelFingerprint: string;

package/dist/src/web-ui/local-runtime/skill-management-routes.d.ts

@@ -0,0 +1,18 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { type PersonalSkillManagementService } from "../../runtime/knowledge-skills/personal-contracts.js";
+import type { JsonObject } from "./contracts.js";
+type SkillManagementRequest = Readonly<{
+    method: string;
+    segments: readonly string[];
+    body: JsonObject | null;
+    environmentId: string;
+    request: IncomingMessage;
+    response: ServerResponse;
+}>;
+/** Personal records only; the runtime owner shares the model Store's lock. */
+export declare class PersonalSkillManagementRoutes {
+    private readonly resolveService;
+    constructor(resolveService: (environmentId: string) => PersonalSkillManagementService | undefined);
+    handle(request: SkillManagementRequest): Promise<boolean>;
+}
+export {};

package/dist/src/web-ui/local-runtime/skill-management-routes.js

@@ -0,0 +1,118 @@
+import { KnowledgeSkillError, PERSONAL_SKILL_LIMITS, } from "../../runtime/knowledge-skills/personal-contracts.js";
+import { acceptConfigMutationRequest } from "./config-mutation-request.js";
+import { sendJson } from "./http.js";
+/** Personal records only; the runtime owner shares the model Store's lock. */
+export class PersonalSkillManagementRoutes {
+    resolveService;
+    constructor(resolveService) {
+        this.resolveService = resolveService;
+    }
+    async handle(request) {
+        const { segments, method, response } = request;
+        if (segments[0] !== "runtime" || segments[1] !== "skills")
+            return false;
+        const isItem = segments.length === 3 && Boolean(segments[2]);
+        const isArchiveAction = segments.length === 4 && Boolean(segments[2]) &&
+            (segments[3] === "archive" || segments[3] === "restore");
+        if (segments.length !== 2 && !isItem && !isArchiveAction)
+            return false;
+        const allow = isArchiveAction ? "POST" : isItem ? "GET, PATCH" : "GET, POST";
+        if (!allow.split(", ").includes(method)) {
+            response.setHeader("allow", allow);
+            sendJson(response, 405, { ok: false, error: "method_not_allowed" });
+            return true;
+        }
+        if (method !== "GET" && !acceptConfigMutationRequest(request.request, response))
+            return true;
+        try {
+            const service = this.resolveService(request.environmentId);
+            if (!service)
+                throw new KnowledgeSkillError("knowledge_skill_management_unavailable");
+            if (segments.length === 2) {
+                if (method === "POST") {
+                    const skill = await service.create(readCreation(request.body));
+                    sendJson(response, 201, { ok: true, skill });
+                }
+                else {
+                    sendJson(response, 200, { ok: true, items: await service.list() });
+                }
+                return true;
+            }
+            const skillId = segments[2];
+            let skill;
+            if (method === "GET") {
+                skill = await service.get(skillId);
+                if (!skill)
+                    throw new KnowledgeSkillError("knowledge_skill_not_found");
+            }
+            else {
+                const expectedRevision = readMutation(request.body, method === "PATCH");
+                if (method === "PATCH") {
+                    skill = await service.updateContent(skillId, expectedRevision, request.body.content);
+                }
+                else if (segments[3] === "archive") {
+                    skill = await service.archive(skillId, expectedRevision);
+                }
+                else {
+                    skill = await service.restore(skillId, expectedRevision);
+                }
+            }
+            sendJson(response, 200, { ok: true, skill });
+        }
+        catch (error) {
+            sendManagementError(response, error);
+        }
+        return true;
+    }
+}
+function readCreation(body) {
+    const allowed = ["name", "description", "content", "environment", "environmentId"];
+    if (!body || Object.keys(body).some((key) => !allowed.includes(key)) ||
+        typeof body.name !== "string" || typeof body.description !== "string" || typeof body.content !== "string") {
+        throw new KnowledgeSkillError("knowledge_skill_input_invalid");
+    }
+    return { name: body.name, description: body.description, content: body.content };
+}
+function readMutation(body, contentRequired) {
+    const allowed = ["expectedRevision", "environment", "environmentId", ...(contentRequired ? ["content"] : [])];
+    if (!body || Object.keys(body).some((key) => !allowed.includes(key)) ||
+        (contentRequired && typeof body.content !== "string")) {
+        throw new KnowledgeSkillError("knowledge_skill_input_invalid");
+    }
+    const revision = body.expectedRevision;
+    if (typeof revision !== "number" || !Number.isSafeInteger(revision) || revision < 1 ||
+        revision > PERSONAL_SKILL_LIMITS.revision) {
+        throw new KnowledgeSkillError("knowledge_skill_revision_invalid");
+    }
+    return revision;
+}
+const ERROR_STATUSES = Object.freeze({
+    knowledge_skill_not_found: 404,
+    knowledge_skill_read_only: 403,
+    knowledge_skill_revision_conflict: 409,
+    knowledge_skill_revision_limit: 409,
+    knowledge_skill_archived: 409,
+    knowledge_skill_input_invalid: 400,
+    knowledge_skill_id_invalid: 400,
+    knowledge_skill_revision_invalid: 400,
+    knowledge_skill_content_invalid: 400,
+    knowledge_skill_content_too_large: 400,
+    knowledge_skill_name_invalid: 400,
+    knowledge_skill_description_invalid: 400,
+    knowledge_skill_storage_unavailable: 503,
+    knowledge_skill_storage_invalid: 503,
+    knowledge_skill_storage_too_large: 503,
+    knowledge_skill_management_unavailable: 503,
+});
+function sendManagementError(response, error) {
+    // RPC reconstructs Error with its code; do not rely on prototype identity.
+    const code = error && typeof error === "object" && "code" in error ? error.code : undefined;
+    if (typeof code === "string" && Object.hasOwn(ERROR_STATUSES, code)) {
+        sendJson(response, ERROR_STATUSES[code], { ok: false, error: code });
+        return;
+    }
+    const unavailable = error instanceof Error && error.message === "local_runtime_service_unavailable";
+    sendJson(response, unavailable ? 503 : 500, {
+        ok: false, error: unavailable ? "knowledge_skill_management_unavailable" : "knowledge_skill_management_failed",
+    });
+}

package/docs/configuration.md

@@ -83,7 +83,7 @@ Provider configs should reference env var names:
 }
 ```
 
-Ollama and OpenAI adapters are included. A host may register another adapter
+Ollama, OpenAI and llama.cpp adapters are included. See [llama.cpp setup and reasoning budgets](llamacpp.md). A host may register another adapter
 through `@abot-ai/runtime/model-gateway`; its config uses that adapter's `type` and
 may place adapter-owned JSON-safe values under `settings`. Merely naming an
 unknown type never selects a fallback provider.
@@ -610,6 +610,16 @@ The common slots and their first tuning targets are:
 | 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.                  |
 
+New OpenAI profiles created through CLI setup, Web onboarding, or model
+addition set `timeoutMs` to `300000` (five minutes) in both
+`calibration["context.compact"]` and `calibration["toolPayload.raw"]`. These
+profile overrides take precedence over the shared 180-second compaction and
+90-second literal-payload defaults; other steps retain their own timeouts.
+Explicit template timeouts are preserved, and existing profiles are not
+migrated automatically. To apply these settings to an existing GPT profile,
+add `"timeoutMs": 300000` to each of those calibration objects, preserving
+their other fields. This does not change reasoning effort.
+
 `timeoutMs` addresses provider latency only; raising it does not improve model
 reasoning. Top-level `contextWindowTokens` declares the concrete model
 profile's physical capacity. Calibration context fields can tune projection

package/docs/installation.md

@@ -13,6 +13,7 @@ This guide covers three entry points:
 - TypeScript-capable host project if using the library directly
 - Optional: an installed and running Ollama service for Ollama model profiles
 - Optional: OpenAI API key for OpenAI model profiles
+- Optional: a running llama.cpp server for [llama.cpp model profiles](llamacpp.md)
 
 ## Prepare Ollama (If Selected)
 
@@ -64,12 +65,15 @@ npx abot start
 
 Open [http://127.0.0.1:5177](http://127.0.0.1:5177). The command binds to
 loopback by default. On a fresh installation, the setup wizard lets you select
-OpenAI or Ollama, enter a concrete model ID, and save the connection. OpenAI
+OpenAI, Ollama or llama.cpp, enter a concrete model ID, and save the connection. OpenAI
 accepts the API key directly in the form and stores it privately in the
 consumer's `.env`. The key is not returned to the browser or stored in runtime
 JSON. Existing OpenAI configurations missing a key open the same completion flow.
 
-For Ollama, the server must already be running with the selected model available.
+For Ollama and llama.cpp, the server must already be running with the selected model available.
+Every provider's model registration includes an explicit thinking-support checkbox.
+llama.cpp additionally offers per-segment token budgets and a metadata-only
+connection check; see [llama.cpp setup](llamacpp.md).
 Its address is resolved from the ABot host, even when you use the UI from a phone.
 Continue through the optional **Embedding** step to configure semantic memory,
 or choose to set it up later. **Plugins** starts with all tools selected for a
@@ -93,7 +97,7 @@ managed by a separate process remains under that process's lifecycle; the UI
 reports when saved changes require that owner to restart.
 
 In the Web UI, open **Models → Add model** to add another model.
-Choose a saved provider connection or create a new OpenAI/Ollama connection.
+Choose a saved provider connection or create a new OpenAI/Ollama/llama.cpp connection.
 Each provider card also has an **Add model** shortcut. Review the model, then
 choose **Save and apply**. Saved API keys are reused; existing model profiles and
 the default model are preserved. The added model is selected in the Models list.
@@ -133,8 +137,10 @@ 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.
+must be restarted. OpenAI and llama.cpp users enter the embedding model id
+manually; Ollama users can discover model ids installed at the configured Ollama
+endpoint. For llama.cpp, use an embedding-enabled server and, if needed, a
+[separate connection from chat](llamacpp.md#embeddings-and-semantic-memory).
 
 See [Passive Long-Term Memory](long-term-memory.md) before enabling persistence.
 

package/docs/llamacpp.md

@@ -0,0 +1,248 @@
+# llama.cpp model connection
+
+ABot includes a **llamacpp** provider alongside Ollama and OpenAI. It connects to
+an independently installed and running llama-server; it does not install,
+start, stop, update or download that server, its models or GPU drivers.
+
+The implementation targets the server protocol in
+[llama.cpp v0.7.0, revision 620d2225](https://github.com/ggml-org/llama.cpp/tree/620d2225cc436ab0b001e3200e590e3b286ef9ab).
+Protocol fixtures exercise that interface. This is a source compatibility
+reference, not a claim that a real server or every model/template was tested.
+Earlier builds may not support the reasoning budget fields.
+
+## Input token counting and compaction
+
+ABot uses `POST /v1/chat/completions/input_tokens` before context admission.
+The endpoint is available in the pinned protocol revision above and performs
+template rendering and tokenization without generating a response. Counting
+uses the same model, projected messages, thinking controls and structured format
+as generation, including the server's chat template and special tokens.
+Structured-output grammar is not charged as additional prompt prose.
+
+Each llama.cpp context assessment requests a fresh count instead of reusing the
+client's token-count cache. The existing context budget and compactor consume
+that measured count, and measure replacement candidates again. The final gateway
+chat guard reuses a matching recent measurement; its existing estimate behavior
+for a missing or expired measurement remains unchanged. Direct public `/raw`
+calls retain their existing estimate guard. OpenAI caching and Ollama estimation
+retain their existing behavior.
+
+An unavailable counting endpoint, invalid response or failed authentication
+fails the count explicitly; ABot does not silently substitute an estimate for
+that failed call. Cancellation aborts counting. The count measures input size,
+not server capacity: `contextWindowTokens` must still match the server's effective
+context allocation.
+
+## Prepare the server
+
+Use the official [llama.cpp server guide](https://github.com/ggml-org/llama.cpp/blob/620d2225cc436ab0b001e3200e590e3b286ef9ab/tools/server/README.md)
+to install a build suitable for your OS/GPU and start your chosen model.
+Set its model alias, effective context capacity, GPU allocation and listening
+address explicitly. The example ABot origin is http://127.0.0.1:8080;
+your server must actually listen there. Use the exact model ID returned by
+the server, not an Ollama model-library name unless it is also your server alias.
+
+The URL is resolved from the ABot Runtime host. A Windows browser does not
+make a WSL or Docker Runtime use Windows loopback. Use an address reachable
+from the Runtime for WSL-to-Windows, container-to-host or remote connections.
+The setup form accepts an HTTP/HTTPS origin without credentials, query or path.
+
+## Register the connection
+
+On a new installation choose **llama.cpp** in setup. For an existing installation,
+open **Models → Add model** and choose a new llama.cpp connection or reuse a
+saved connection.
+
+Enter the model ID, physical context capacity and server origin. The context
+value must match the effective per-request capacity configured by the server;
+it is not an instruction to resize the server. The API key is optional for a
+server without authentication. If supplied, ABot writes a private isolated
+credential binding in .env, not a key inside the model JSON or browser state.
+An existing saved connection retains its authentication settings.
+
+**Check connection** reads GET /health and GET /v1/models only.
+It never generates a response or saves settings. Server readiness does not prove
+thinking support, tool support, image support or context capacity.
+
+The **This model supports thinking** checkbox is available for all providers.
+It declares a model capability; enable it only when the selected model supports
+reasoning. Newly created llama.cpp profiles start with text input only and
+thinking support disabled. No capability is inferred from the model name.
+
+## Thinking budget
+
+For a llama.cpp model with thinking support enabled, setup and the model editor
+offer a default budget. Invocation calibration can override that model default.
+
+- **Inherit (no override):** omits the budget at that configuration layer.
+- **Server default:** explicitly asks llama-server to use its configured default;
+  this may itself be a finite budget.
+- **Token limit:** a whole number from 0 through 2147483647 for each
+  reasoning segment. Zero disables thinking; a positive value limits its tokens.
+
+A budget is not a wall-clock timeout or a total user-request allowance.
+One user request can invoke the model several times; each invocation may contain
+more than one reasoning segment. The server can need closing tokens after the
+limit and the final answer still needs output/context capacity.
+The model's chat template must support thinking and the server's closing-tag
+mechanism. A successful health check cannot validate that behavior.
+
+The request-level **Off** control overrides a saved budget. Numeric limits are
+only offered for llama.cpp; Ollama and OpenAI retain their existing effort
+controls. A finite budget does not change ABot's role policy, approval rules
+or tool permissions.
+
+### Shared modes and optional overrides
+
+Chat, SPARK, schedules and automation agents expose the shared **Low / Reasoning /
+Deep** choices. Their default wire values remain `none / medium / high`, subject
+to existing profile and invocation calibration. A model's template determines
+whether positive effort levels differ. Chat exposes separate menus for reasoning
+depth and thinking budget; the other forms expose separate controls. A manual
+token limit or server default preserves the effective positive effort, and
+choosing a mode retains that budget. For example, Deep and a 512-token limit can
+be selected together. Selecting a mode clears an explicit manual Thinking Off
+setting so the newly chosen mode can take effect.
+
+Selecting a positive budget or server default when the ordinary effort is
+`none` enables thinking with `medium`; a zero budget disables thinking without
+rewriting the saved effort. An explicit invocation override still wins. Choosing
+Profile default in the budget menu removes only the manual budget, preserving
+the selected mode.
+
+The model editor also offers **Mode token overrides**. The optional
+`generation.reasoningBudgetByMode` map accepts `fast`, `reasoning` and `deep`,
+each with a non-negative integer limit. Zero disables thinking for that mode.
+No mode limits are supplied automatically.
+For example, `"reasoningBudgetByMode": { "fast": 32, "deep": 512 }` enables
+bounded thinking for Low and Deep while Reasoning keeps the ordinary settings.
+These numbers are illustrative, not application defaults.
+
+A matching mode limit replaces the ordinary `reasoningBudget`. A positive limit
+enables thinking even when Low or the profile effort would otherwise disable it;
+an already positive configured effort is preserved. A zero limit disables
+thinking. Explicit invocation effort and request-level Off still take precedence. Per-mode maps apply only to main model
+steps and direct gateway calls; utility steps such as `context.compact` retain
+their own calibration and ignore conversation mode budgets.
+
+Configuration overlays replace the entire map. Omitting the field inherits the
+parent map, while `{}` explicitly clears inherited mode limits. Blank entries in
+a custom map use the ordinary effort and budget settings; they do not inherit individual
+entries from the replaced map.
+
+~~~json
+{
+  "provider": "local-llama",
+  "model": "gemma",
+  "supportsThinking": true,
+  "contextWindowTokens": 32768,
+  "capabilities": { "inputModalities": ["text"] },
+  "generation": {
+    "reasoningBudget": { "mode": "tokens", "tokens": 512 }
+  },
+  "calibration": {
+    "context.compact": {
+      "generation": { "reasoningBudget": { "mode": "server-default" } }
+    }
+  }
+}
+~~~
+
+Provider connection in runtime.config.json:
+
+~~~json
+{
+  "models": {
+    "providers": {
+      "local-llama": {
+        "type": "llamacpp",
+        "baseUrl": "http://127.0.0.1:8080"
+      }
+    },
+    "profiles": {
+      "gemma": { "configRef": "./models/gemma.config.json" }
+    }
+  }
+}
+~~~
+
+For authenticated servers add an apiKeyEnv name and supply its key privately.
+The wizard creates an isolated name automatically.
+
+## Command-line setup
+
+~~~bash
+npx abot init --provider llamacpp --model gemma --base-url http://127.0.0.1:8080 --context-window 32768 --supports-thinking true --reasoning-budget 512
+npx abot add-model --profile gemma-llama --provider llamacpp --model gemma --base-url http://127.0.0.1:8080 --supports-thinking true --reasoning-budget server-default
+~~~
+
+For an authenticated connection add --api-key-env MY_LLAMA_KEY and set that
+environment variable privately. Do not put an API secret in command arguments.
+--supports-thinking true|false is also available for Ollama/OpenAI registration;
+--reasoning-budget requires llama.cpp and explicit thinking support.
+
+The add command preserves existing profiles and the selected default unless
+--default is supplied. A reused provider ID must keep its existing endpoint.
+Restart the owning gateway/ABot process after CLI changes. Web UI **Save and
+apply** reloads an owned gateway or reports when an external owner must restart.
+
+## Embeddings and semantic memory
+
+The llama.cpp adapter supports text embeddings through `/v1/embeddings`.
+Use a dedicated embedding model and run its llama-server with `--embedding`
+and a pooling mode other than `none`, as required by the official server API.
+A chat model with thinking support does not automatically support embeddings.
+
+In the setup wizard's memory step, choose an existing llama.cpp connection or
+create another one for the embedding server. On an existing installation, open
+**Memory → Setup → Add connection** to use the same form. A separate embedding server uses
+its own address and optional API key; it does not replace the chat connection.
+For example, chat can use port 8080 while embeddings use port 8081. Enter the
+embedding model's exact server ID manually. Model listing and a health check do
+not establish embedding support. **Test and save** sends an embedding probe and
+enables memory only when that probe succeeds.
+
+Existing installations can select a configured llama.cpp connection in memory
+settings. Embeddings use the existing `models.embeddingProfiles` configuration,
+independently of chat profiles and reasoning budgets. A manual configuration
+fragment for a separate embedding connection is:
+
+~~~json
+{
+  "models": {
+    "providers": {
+      "llama-embeddings": {
+        "type": "llamacpp",
+        "baseUrl": "http://127.0.0.1:8081"
+      }
+    },
+    "embeddingProfiles": {
+      "memory-embedding": {
+        "provider": "llama-embeddings",
+        "model": "your-embedding-model-alias"
+      }
+    }
+  },
+  "longTermMemory": {
+    "enabled": true,
+    "embeddingProfileId": "memory-embedding"
+  }
+}
+~~~
+
+The adapter validates response indices, vector count, dimensions and finite
+values, and uses the existing cancellation and model-fingerprint contracts.
+Semantic memory can also continue using a separate Ollama/OpenAI connection.
+
+## Boundaries and validation
+
+Image input is not advertised. Embedding support does not change memory admission,
+retention, retrieval or approval policy. No embedding model is installed or
+selected automatically.
+
+Validate real model behavior separately: ordinary text, structured decisions,
+tool/result continuation, generated file contents, cancellation and stream
+completion. Compare timing and output quality with thinking off, a finite budget
+and server default under the same model/context/server configuration. Provider
+traces record resolved controls and native usage when supplied; ABot does not
+invent a budget-exhaustion event or a reasoning-token count.

package/docs/long-term-memory.md

@@ -194,6 +194,15 @@ 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.
 
+Choose **Add connection** to configure an embedding server directly from this
+screen. The shared setup form supports OpenAI, Ollama and llama.cpp; llama.cpp
+can have a separate connection even when a chat connection already exists.
+Enter its server URL, model ID and optional key, then choose **Test and save**.
+The selected memory profile, lifecycle-event setting and plugin policy are
+preserved. If the probe fails after the connection is saved, it remains available
+for retry and the previous memory binding stays in place. After a successful
+save, choose **Apply & restart** or close the dialog and apply later.
+
 ## Configuration Contract
 
 The onboarding flow writes a dedicated embedding profile and binds the feature
@@ -233,6 +242,9 @@ or memory lifecycle event is added to the response path.
   model ids through `/api/tags`.
 - OpenAI uses `/embeddings`. Model discovery is not exposed by that provider,
   so the consumer supplies the embedding model id.
+- llama.cpp uses `/v1/embeddings` with a manually supplied embedding model id.
+  Use an embedding-enabled server; setup can register a separate connection
+  without changing the chat server. See [llama.cpp setup](llamacpp.md#embeddings-and-semantic-memory).
 - A custom model-gateway adapter may implement `embed` and optional
   `listEmbeddingModels` without changing Runtime memory policy.
 

package/docs/running-locally.md

@@ -3,7 +3,7 @@
 `abot` is a runtime library plus local service entrypoints. A complete
 source-checkout setup usually has:
 
-- a model provider, such as Ollama or OpenAI
+- a model provider, such as Ollama, OpenAI or llama.cpp
 - the model gateway process
 - the runtime bridge client process
 - optionally the local web UI proxy
@@ -79,6 +79,12 @@ hosts may use a different address. Run the `/api/tags` check against the chosen
 URL from the runtime environment. You can also edit
 `models.providers.ollama.baseUrl` in `local/runtime.config.json` later.
 
+### llama.cpp
+
+See [llama.cpp setup](llamacpp.md) for a separately managed server, reachable origin,
+optional authentication and thinking-budget configuration. Model server lifecycle
+is independent of ABot and its internal model gateway.
+
 ### OpenAI
 
 Set the API key in `.env`: