Vendor OpenClaw source as Adolf fork baseline

Adolf is a fork/vendored clone of github.com/openclaw/openclaw (v2026.6.11),
free to diverge. Tree copied sans upstream .git; upstream remote added for
future syncs. Node pinned to 24 (.nvmrc); engines already require >=22.19.
Preserves docs/ARCHITECTURE.md.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LeqyaxJF2nbRXJtae2kNB2

extensions/llama-cpp/README.md

@@ -0,0 +1,27 @@
+# @openclaw/llama-cpp-provider
+
+Official llama.cpp embedding provider for OpenClaw.
+
+This plugin runs local GGUF embedding models through `node-llama-cpp`.
+
+## Install
+
+```bash
+openclaw plugins install @openclaw/llama-cpp-provider
+```
+
+Restart the Gateway after installing or updating the plugin. Use Node 24 for
+native installs and updates.
+
+## Configure
+
+Set `agents.defaults.memorySearch.provider` to `local`. By default, the plugin
+downloads and uses the EmbeddingGemma GGUF model. Configure
+`agents.defaults.memorySearch.local.modelPath` to use another local path, Hugging
+Face model URI, or HTTPS model URL.
+
+## Package
+
+- Plugin id: `llama-cpp`
+- Package: `@openclaw/llama-cpp-provider`
+- Minimum OpenClaw host: `2026.6.2`

extensions/llama-cpp/index.test.ts

@@ -0,0 +1,445 @@
+import os from "node:os";
+import path from "node:path";
+import {
+  createPluginRegistryFixture,
+  registerVirtualTestPlugin,
+} from "openclaw/plugin-sdk/plugin-test-contracts";
+import {
+  clearEmbeddingProviders,
+  clearMemoryEmbeddingProviders,
+  getRegisteredEmbeddingProvider,
+} from "openclaw/plugin-sdk/plugin-test-runtime";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+const memoryHostEmbeddingMocks = vi.hoisted(() => ({
+  createLocalEmbeddingProvider: vi.fn(),
+}));
+
+vi.mock("openclaw/plugin-sdk/memory-core-host-engine-embeddings", () => ({
+  createLocalEmbeddingProvider: memoryHostEmbeddingMocks.createLocalEmbeddingProvider,
+}));
+
+import llamaCppPlugin from "./index.js";
+import {
+  DEFAULT_LLAMA_CPP_EMBEDDING_MODEL,
+  createLlamaCppMemoryEmbeddingProvider,
+  formatLlamaCppSetupError,
+  llamaCppEmbeddingProviderAdapter,
+} from "./src/embedding-provider.js";
+
+afterEach(() => {
+  clearEmbeddingProviders();
+  clearMemoryEmbeddingProviders();
+  memoryHostEmbeddingMocks.createLocalEmbeddingProvider.mockReset();
+});
+
+describe("llama.cpp provider plugin", () => {
+  it("registers the local embedding provider through the generic SDK contract", () => {
+    const { config, registry } = createPluginRegistryFixture();
+
+    registerVirtualTestPlugin({
+      registry,
+      config,
+      id: "llama-cpp",
+      name: "llama.cpp Provider",
+      contracts: {
+        embeddingProviders: ["local"],
+      },
+      register: llamaCppPlugin.register,
+    });
+
+    const provider = getRegisteredEmbeddingProvider("local");
+    expect(provider?.ownerPluginId).toBe("llama-cpp");
+    expect(provider?.adapter).toMatchObject({
+      id: "local",
+      defaultModel: DEFAULT_LLAMA_CPP_EMBEDDING_MODEL,
+      transport: "local",
+    });
+  });
+
+  it("adapts the worker-backed local embedding provider", async () => {
+    const close = vi.fn();
+    memoryHostEmbeddingMocks.createLocalEmbeddingProvider.mockResolvedValue({
+      id: "local",
+      model: DEFAULT_LLAMA_CPP_EMBEDDING_MODEL,
+      maxInputTokens: 2048,
+      embedQuery: vi.fn(async () => [0.6, 0.8]),
+      embedBatchInputs: vi.fn(async () => [[0.3, 0.4]]),
+      embedBatch: vi.fn(async () => [[1, 0]]),
+      close,
+    });
+    const abortController = new AbortController();
+
+    const result = await llamaCppEmbeddingProviderAdapter.create({
+      config: {},
+      provider: "local",
+      model: "text-embedding-3-small",
+    });
+    const provider = result.provider;
+    expect(provider).not.toBeNull();
+    if (!provider) {
+      throw new Error("expected llama.cpp provider");
+    }
+
+    await expect(provider.embed("hello")).resolves.toEqual([0.6, 0.8]);
+    await expect(
+      provider.embedBatch([{ text: "doc" }], { signal: abortController.signal }),
+    ).resolves.toEqual([[0.3, 0.4]]);
+    await provider.close?.();
+
+    expect(provider.model).toBe(DEFAULT_LLAMA_CPP_EMBEDDING_MODEL);
+    expect(provider.maxInputTokens).toBe(2048);
+    expect(close).toHaveBeenCalledTimes(1);
+    expect(memoryHostEmbeddingMocks.createLocalEmbeddingProvider).toHaveBeenCalledWith(
+      {
+        config: {},
+        provider: "local",
+        fallback: "none",
+        model: DEFAULT_LLAMA_CPP_EMBEDDING_MODEL,
+        local: {
+          modelPath: DEFAULT_LLAMA_CPP_EMBEDDING_MODEL,
+        },
+      },
+      {
+        nodeLlamaCppImportUrl: expect.stringContaining("node-llama-cpp"),
+      },
+    );
+    const workerProvider =
+      await memoryHostEmbeddingMocks.createLocalEmbeddingProvider.mock.results[0].value;
+    expect(workerProvider.embedBatchInputs).toHaveBeenCalledWith([{ text: "doc" }], {
+      signal: abortController.signal,
+    });
+  });
+
+  it("includes output dimensionality in local cache and index identities", async () => {
+    memoryHostEmbeddingMocks.createLocalEmbeddingProvider.mockResolvedValue({
+      id: "local",
+      model: DEFAULT_LLAMA_CPP_EMBEDDING_MODEL,
+      embedQuery: vi.fn(),
+      embedBatch: vi.fn(),
+    });
+
+    const result = await createLlamaCppMemoryEmbeddingProvider(
+      {
+        config: {},
+        provider: "local",
+        fallback: "none",
+        model: DEFAULT_LLAMA_CPP_EMBEDDING_MODEL,
+        outputDimensionality: 512,
+      },
+      { nodeLlamaCppImportUrl: "file:///plugin/node-llama-cpp.js" },
+    );
+    const resolvedIdentity = llamaCppEmbeddingProviderAdapter.resolveIndexIdentity?.({
+      config: {},
+      provider: "local",
+      model: DEFAULT_LLAMA_CPP_EMBEDDING_MODEL,
+      dimensions: 512,
+    });
+
+    expect(result.runtime?.cacheKeyData).toMatchObject({ outputDimensionality: 512 });
+    expect(result.runtime?.indexIdentityAliases).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          cacheKeyData: expect.objectContaining({ outputDimensionality: 512 }),
+        }),
+      ]),
+    );
+    expect(resolvedIdentity?.cacheKeyData).toMatchObject({ outputDimensionality: 512 });
+    expect(resolvedIdentity?.aliases).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          cacheKeyData: expect.objectContaining({ outputDimensionality: 512 }),
+        }),
+      ]),
+    );
+  });
+
+  it("keeps the default model identity when configured with its exact cache artifact path", async () => {
+    const modelPath = path.join(
+      os.homedir(),
+      ".node-llama-cpp",
+      "models",
+      "hf_ggml-org_embeddinggemma-300m-qat-Q8_0.gguf",
+    );
+    memoryHostEmbeddingMocks.createLocalEmbeddingProvider.mockResolvedValue({
+      id: "local",
+      model: modelPath,
+      embedQuery: vi.fn(),
+      embedBatch: vi.fn(),
+    });
+
+    const result = await createLlamaCppMemoryEmbeddingProvider(
+      {
+        config: {},
+        provider: "local",
+        fallback: "none",
+        model: modelPath,
+        local: { modelPath },
+      },
+      { nodeLlamaCppImportUrl: "file:///plugin/node-llama-cpp.js" },
+    );
+
+    expect(result.provider?.model).toBe(DEFAULT_LLAMA_CPP_EMBEDDING_MODEL);
+    expect(result.runtime?.cacheKeyData).toEqual({
+      provider: "local",
+      model: DEFAULT_LLAMA_CPP_EMBEDDING_MODEL,
+    });
+    expect(result.runtime?.indexIdentityAliases).toEqual([
+      {
+        model: modelPath,
+        cacheKeyData: {
+          provider: "local",
+          model: modelPath,
+        },
+      },
+      {
+        model: "hf_ggml-org_embeddinggemma-300m-qat-Q8_0.gguf",
+        cacheKeyData: {
+          provider: "local",
+          model: "hf_ggml-org_embeddinggemma-300m-qat-Q8_0.gguf",
+        },
+      },
+    ]);
+    expect(
+      llamaCppEmbeddingProviderAdapter.resolveIndexIdentity?.({
+        config: {},
+        provider: "local",
+        model: modelPath,
+        local: { modelPath },
+      }),
+    ).toEqual({
+      model: DEFAULT_LLAMA_CPP_EMBEDDING_MODEL,
+      cacheKeyData: {
+        provider: "local",
+        model: DEFAULT_LLAMA_CPP_EMBEDDING_MODEL,
+      },
+      aliases: [
+        {
+          model: modelPath,
+          cacheKeyData: {
+            provider: "local",
+            model: modelPath,
+          },
+        },
+        {
+          model: "hf_ggml-org_embeddinggemma-300m-qat-Q8_0.gguf",
+          cacheKeyData: {
+            provider: "local",
+            model: "hf_ggml-org_embeddinggemma-300m-qat-Q8_0.gguf",
+          },
+        },
+      ],
+    });
+    expect(memoryHostEmbeddingMocks.createLocalEmbeddingProvider).toHaveBeenCalledWith(
+      expect.objectContaining({
+        model: modelPath,
+        local: { modelPath },
+      }),
+      {
+        nodeLlamaCppImportUrl: "file:///plugin/node-llama-cpp.js",
+      },
+    );
+  });
+
+  it("keeps an arbitrary same-basename model path as a distinct identity", async () => {
+    const modelPath = path.join(
+      os.tmpdir(),
+      "custom-models",
+      DEFAULT_LLAMA_CPP_EMBEDDING_MODEL.split("/").at(-1)!,
+    );
+    memoryHostEmbeddingMocks.createLocalEmbeddingProvider.mockResolvedValue({
+      id: "local",
+      model: modelPath,
+      embedQuery: vi.fn(),
+      embedBatch: vi.fn(),
+    });
+
+    const result = await createLlamaCppMemoryEmbeddingProvider(
+      {
+        config: {},
+        provider: "local",
+        fallback: "none",
+        model: modelPath,
+        local: { modelPath },
+      },
+      { nodeLlamaCppImportUrl: "file:///plugin/node-llama-cpp.js" },
+    );
+
+    expect(result.provider?.model).toBe(modelPath);
+    expect(result.runtime?.cacheKeyData).toEqual({
+      provider: "local",
+      model: modelPath,
+    });
+    expect(result.runtime).not.toHaveProperty("indexIdentityAliases");
+  });
+
+  it("keeps a bare same-basename file in the default cache as a distinct identity", async () => {
+    const modelPath = path.join(
+      os.homedir(),
+      ".node-llama-cpp",
+      "models",
+      DEFAULT_LLAMA_CPP_EMBEDDING_MODEL.split("/").at(-1)!,
+    );
+    memoryHostEmbeddingMocks.createLocalEmbeddingProvider.mockResolvedValue({
+      id: "local",
+      model: modelPath,
+      embedQuery: vi.fn(),
+      embedBatch: vi.fn(),
+    });
+
+    const result = await createLlamaCppMemoryEmbeddingProvider(
+      {
+        config: {},
+        provider: "local",
+        fallback: "none",
+        model: modelPath,
+        local: { modelPath },
+      },
+      { nodeLlamaCppImportUrl: "file:///plugin/node-llama-cpp.js" },
+    );
+
+    expect(result.provider?.model).toBe(modelPath);
+    expect(result.runtime).not.toHaveProperty("indexIdentityAliases");
+  });
+
+  it("keeps the default model identity with a custom cache directory", async () => {
+    const modelCacheDir = path.join(os.tmpdir(), "llama-cpp-model-cache");
+    const modelPath = path.join(modelCacheDir, "hf_ggml-org_embeddinggemma-300m-qat-Q8_0.gguf");
+    memoryHostEmbeddingMocks.createLocalEmbeddingProvider.mockResolvedValue({
+      id: "local",
+      model: modelPath,
+      embedQuery: vi.fn(),
+      embedBatch: vi.fn(),
+    });
+
+    const result = await createLlamaCppMemoryEmbeddingProvider(
+      {
+        config: {},
+        provider: "local",
+        fallback: "none",
+        model: DEFAULT_LLAMA_CPP_EMBEDDING_MODEL,
+        local: { modelPath: DEFAULT_LLAMA_CPP_EMBEDDING_MODEL, modelCacheDir },
+      },
+      { nodeLlamaCppImportUrl: "file:///plugin/node-llama-cpp.js" },
+    );
+
+    expect(result.provider?.model).toBe(DEFAULT_LLAMA_CPP_EMBEDDING_MODEL);
+    expect(result.runtime?.cacheKeyData).toEqual({
+      provider: "local",
+      model: DEFAULT_LLAMA_CPP_EMBEDDING_MODEL,
+    });
+    expect(result.runtime?.indexIdentityAliases).toEqual([
+      {
+        model: modelPath,
+        cacheKeyData: {
+          provider: "local",
+          model: modelPath,
+        },
+      },
+      {
+        model: "hf_ggml-org_embeddinggemma-300m-qat-Q8_0.gguf",
+        cacheKeyData: {
+          provider: "local",
+          model: "hf_ggml-org_embeddinggemma-300m-qat-Q8_0.gguf",
+        },
+      },
+    ]);
+  });
+
+  it.each([
+    {
+      direction: "default URI to exact relative cache artifact",
+      modelPath: DEFAULT_LLAMA_CPP_EMBEDDING_MODEL,
+    },
+    {
+      direction: "exact relative cache artifact to default URI",
+      modelPath: "hf_ggml-org_embeddinggemma-300m-qat-Q8_0.gguf",
+    },
+  ])("keeps $direction compatible", ({ modelPath }) => {
+    const modelCacheDir = path.join(os.tmpdir(), "llama-cpp-relative-model-cache");
+    const relativeModelPath = "hf_ggml-org_embeddinggemma-300m-qat-Q8_0.gguf";
+    const resolvedModelPath = path.join(modelCacheDir, relativeModelPath);
+
+    expect(
+      llamaCppEmbeddingProviderAdapter.resolveIndexIdentity?.({
+        config: {},
+        provider: "local",
+        model: modelPath,
+        local: { modelPath, modelCacheDir },
+      }),
+    ).toEqual({
+      model: DEFAULT_LLAMA_CPP_EMBEDDING_MODEL,
+      cacheKeyData: {
+        provider: "local",
+        model: DEFAULT_LLAMA_CPP_EMBEDDING_MODEL,
+      },
+      aliases: [
+        {
+          model: resolvedModelPath,
+          cacheKeyData: {
+            provider: "local",
+            model: resolvedModelPath,
+          },
+        },
+        {
+          model: relativeModelPath,
+          cacheKeyData: {
+            provider: "local",
+            model: relativeModelPath,
+          },
+        },
+      ],
+    });
+  });
+
+  it("keeps the default model identity for its exact relative cache artifact", async () => {
+    const modelCacheDir = path.join(os.tmpdir(), "llama-cpp-relative-model-cache");
+    const modelPath = "hf_ggml-org_embeddinggemma-300m-qat-Q8_0.gguf";
+    const resolvedModelPath = path.join(modelCacheDir, modelPath);
+    memoryHostEmbeddingMocks.createLocalEmbeddingProvider.mockResolvedValue({
+      id: "local",
+      model: modelPath,
+      embedQuery: vi.fn(),
+      embedBatch: vi.fn(),
+    });
+
+    const result = await createLlamaCppMemoryEmbeddingProvider(
+      {
+        config: {},
+        provider: "local",
+        fallback: "none",
+        model: modelPath,
+        local: { modelPath, modelCacheDir },
+      },
+      { nodeLlamaCppImportUrl: "file:///plugin/node-llama-cpp.js" },
+    );
+
+    expect(result.provider?.model).toBe(DEFAULT_LLAMA_CPP_EMBEDDING_MODEL);
+    expect(result.runtime?.indexIdentityAliases).toEqual([
+      {
+        model: resolvedModelPath,
+        cacheKeyData: {
+          provider: "local",
+          model: resolvedModelPath,
+        },
+      },
+      {
+        model: modelPath,
+        cacheKeyData: {
+          provider: "local",
+          model: modelPath,
+        },
+      },
+    ]);
+  });
+
+  it("formats missing runtime errors with the plugin install command", () => {
+    const err = Object.assign(new Error("Cannot find package 'node-llama-cpp'"), {
+      code: "ERR_MODULE_NOT_FOUND",
+    });
+
+    expect(formatLlamaCppSetupError(err)).toContain(
+      "openclaw plugins install @openclaw/llama-cpp-provider",
+    );
+  });
+});

extensions/llama-cpp/index.ts

@@ -0,0 +1,11 @@
+import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
+import { llamaCppEmbeddingProviderAdapter } from "./src/embedding-provider.js";
+
+export default definePluginEntry({
+  id: "llama-cpp",
+  name: "llama.cpp Provider",
+  description: "Local GGUF embeddings through node-llama-cpp",
+  register(api) {
+    api.registerEmbeddingProvider(llamaCppEmbeddingProviderAdapter);
+  },
+});

extensions/llama-cpp/openclaw.plugin.json

@@ -0,0 +1,17 @@
+{
+  "id": "llama-cpp",
+  "name": "llama.cpp Provider",
+  "description": "Local GGUF embeddings through node-llama-cpp.",
+  "activation": {
+    "onStartup": false
+  },
+  "enabledByDefault": true,
+  "contracts": {
+    "embeddingProviders": ["local"]
+  },
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}

extensions/llama-cpp/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@openclaw/llama-cpp-provider",
+  "version": "2026.6.11",
+  "description": "OpenClaw llama.cpp embedding provider plugin",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/openclaw/openclaw"
+  },
+  "type": "module",
+  "optionalDependencies": {
+    "node-llama-cpp": "3.19.0"
+  },
+  "devDependencies": {
+    "@openclaw/plugin-sdk": "workspace:*"
+  },
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "install": {
+      "npmSpec": "@openclaw/llama-cpp-provider",
+      "defaultChoice": "npm",
+      "minHostVersion": ">=2026.6.2"
+    },
+    "compat": {
+      "pluginApi": ">=2026.6.11"
+    },
+    "build": {
+      "openclawVersion": "2026.6.11"
+    },
+    "release": {
+      "bundleRuntimeDependencies": false,
+      "publishToClawHub": true,
+      "publishToNpm": true
+    }
+  }
+}

extensions/llama-cpp/src/embedding-provider.ts

@@ -0,0 +1,270 @@
+import { createRequire } from "node:module";
+import os from "node:os";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import type {
+  EmbeddingInput,
+  EmbeddingProvider,
+  EmbeddingProviderAdapter,
+  EmbeddingProviderCreateOptions,
+  EmbeddingProviderCreateResult,
+} from "openclaw/plugin-sdk/embedding-providers";
+import {
+  createLocalEmbeddingProvider,
+  type EmbeddingInput as MemoryEmbeddingInput,
+  type MemoryEmbeddingProvider,
+  type MemoryEmbeddingProviderCreateOptions,
+  type MemoryEmbeddingProviderCreateResult,
+} from "openclaw/plugin-sdk/memory-core-host-engine-embeddings";
+
+type LlamaCppLocalOptions = {
+  modelPath?: string;
+  modelCacheDir?: string;
+  contextSize?: number | "auto";
+};
+
+export type LlamaCppEmbeddingProviderRuntimeOptions = {
+  nodeLlamaCppImportUrl?: string;
+};
+
+export const LLAMA_CPP_EMBEDDING_PROVIDER_ID = "local";
+export const DEFAULT_LLAMA_CPP_EMBEDDING_MODEL =
+  "hf:ggml-org/embeddinggemma-300m-qat-q8_0-GGUF/embeddinggemma-300m-qat-Q8_0.gguf";
+const DEFAULT_LLAMA_CPP_EMBEDDING_MODEL_CACHE_FILE_NAME =
+  "hf_ggml-org_embeddinggemma-300m-qat-Q8_0.gguf";
+
+type LlamaCppModelIdentity = {
+  model: string;
+  cacheKeyData: Record<string, unknown>;
+  aliases: Array<{
+    model: string;
+    cacheKeyData: Record<string, unknown>;
+  }>;
+};
+
+function normalizeOptionalString(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
+function readLocalOptions(options: { local?: unknown }): LlamaCppLocalOptions {
+  const local = options.local as LlamaCppLocalOptions | undefined;
+  return local ?? {};
+}
+
+function createLlamaCppCacheKeyData(
+  model: string,
+  outputDimensionality?: number,
+): Record<string, unknown> {
+  return {
+    provider: LLAMA_CPP_EMBEDDING_PROVIDER_ID,
+    model,
+    ...(typeof outputDimensionality === "number" ? { outputDimensionality } : {}),
+  };
+}
+
+function resolveLlamaCppModelIdentity(
+  local: LlamaCppLocalOptions,
+  modelPath: string,
+  outputDimensionality?: number,
+): LlamaCppModelIdentity {
+  const modelCacheDir =
+    normalizeOptionalString(local.modelCacheDir) ??
+    path.join(os.homedir(), ".node-llama-cpp", "models");
+  const resolvedDefaultModelPath = path.resolve(
+    modelCacheDir,
+    DEFAULT_LLAMA_CPP_EMBEDDING_MODEL_CACHE_FILE_NAME,
+  );
+  const isModelUri = /^(?:hf:|https?:\/\/)/i.test(modelPath);
+  const resolvedModelPath = isModelUri ? undefined : path.resolve(modelCacheDir, modelPath);
+  // node-llama-cpp resolves the default HF URI to this exact cache target and
+  // accepts its URI-derived filename relative to any configured cache directory.
+  // Preserve that exact historical key; arbitrary filenames and paths stay distinct.
+  if (
+    modelPath !== DEFAULT_LLAMA_CPP_EMBEDDING_MODEL &&
+    resolvedModelPath !== resolvedDefaultModelPath
+  ) {
+    return {
+      model: modelPath,
+      cacheKeyData: createLlamaCppCacheKeyData(modelPath, outputDimensionality),
+      aliases: [],
+    };
+  }
+  const aliasModels = new Set([
+    resolvedDefaultModelPath,
+    DEFAULT_LLAMA_CPP_EMBEDDING_MODEL_CACHE_FILE_NAME,
+  ]);
+  if (modelPath !== DEFAULT_LLAMA_CPP_EMBEDDING_MODEL) {
+    aliasModels.add(modelPath);
+  }
+  return {
+    model: DEFAULT_LLAMA_CPP_EMBEDDING_MODEL,
+    cacheKeyData: createLlamaCppCacheKeyData(
+      DEFAULT_LLAMA_CPP_EMBEDDING_MODEL,
+      outputDimensionality,
+    ),
+    aliases: Array.from(aliasModels, (aliasModel) => ({
+      model: aliasModel,
+      cacheKeyData: createLlamaCppCacheKeyData(aliasModel, outputDimensionality),
+    })),
+  };
+}
+
+function textFromEmbeddingInput(input: EmbeddingInput): string {
+  return typeof input === "string" ? input : input.text;
+}
+
+function toMemoryEmbeddingInput(input: EmbeddingInput): MemoryEmbeddingInput {
+  return typeof input === "string" ? { text: input } : input;
+}
+
+function isNodeLlamaCppMissing(err: unknown): boolean {
+  if (!(err instanceof Error)) {
+    return false;
+  }
+  const code = (err as Error & { code?: unknown }).code;
+  return code === "ERR_MODULE_NOT_FOUND" && err.message.includes("node-llama-cpp");
+}
+
+function formatErrorMessage(err: unknown): string {
+  if (err instanceof Error) {
+    return err.message;
+  }
+  return String(err);
+}
+
+export function formatLlamaCppSetupError(err: unknown): string {
+  const detail = formatErrorMessage(err);
+  const missing = isNodeLlamaCppMissing(err);
+  return [
+    "Local llama.cpp embeddings unavailable.",
+    missing
+      ? "Reason: node-llama-cpp is missing or failed to install."
+      : detail
+        ? `Reason: ${detail}`
+        : undefined,
+    missing && detail ? `Detail: ${detail}` : null,
+    "To enable local GGUF embeddings:",
+    "1) Install the official provider plugin: openclaw plugins install @openclaw/llama-cpp-provider",
+    "2) Use Node 24 for native installs/updates.",
+    "3) If you use pnpm from source: pnpm approve-builds, then pnpm rebuild node-llama-cpp.",
+    'Or set agents.defaults.memorySearch.provider to a remote embedding provider such as "openai", "ollama", "lmstudio", or "voyage".',
+  ]
+    .filter(Boolean)
+    .join("\n");
+}
+
+const requireFromPlugin = createRequire(import.meta.url);
+
+export function resolveNodeLlamaCppImportUrl(): string {
+  return pathToFileURL(requireFromPlugin.resolve("node-llama-cpp")).href;
+}
+
+function adaptMemoryEmbeddingProvider(provider: MemoryEmbeddingProvider): EmbeddingProvider {
+  return {
+    id: LLAMA_CPP_EMBEDDING_PROVIDER_ID,
+    model: provider.model,
+    maxInputTokens: provider.maxInputTokens,
+    embed: async (input, callOptions) =>
+      await provider.embedQuery(textFromEmbeddingInput(input), {
+        signal: callOptions?.signal,
+      }),
+    embedBatch: async (inputs, callOptions) => {
+      if (provider.embedBatchInputs) {
+        return await provider.embedBatchInputs(inputs.map(toMemoryEmbeddingInput), {
+          signal: callOptions?.signal,
+        });
+      }
+      return await provider.embedBatch(inputs.map(textFromEmbeddingInput), {
+        signal: callOptions?.signal,
+      });
+    },
+    close: provider.close,
+  };
+}
+
+export async function createLlamaCppMemoryEmbeddingProvider(
+  options: MemoryEmbeddingProviderCreateOptions,
+  runtimeOptions: LlamaCppEmbeddingProviderRuntimeOptions = {},
+): Promise<MemoryEmbeddingProviderCreateResult> {
+  const createOptions = buildMemoryCreateOptions(options, options.outputDimensionality);
+  const local = readLocalOptions(createOptions);
+  const provider = await createLocalEmbeddingProvider(createOptions, {
+    nodeLlamaCppImportUrl: runtimeOptions.nodeLlamaCppImportUrl ?? resolveNodeLlamaCppImportUrl(),
+  });
+  const identity = resolveLlamaCppModelIdentity(
+    local,
+    provider.model,
+    createOptions.outputDimensionality,
+  );
+  const identifiedProvider =
+    identity.model === provider.model ? provider : { ...provider, model: identity.model };
+  return {
+    provider: identifiedProvider,
+    runtime: createLlamaCppEmbeddingProviderRuntime(identity),
+  };
+}
+
+async function createLlamaCppEmbeddingProviderResult(
+  options: EmbeddingProviderCreateOptions,
+  runtimeOptions: LlamaCppEmbeddingProviderRuntimeOptions = {},
+): Promise<EmbeddingProviderCreateResult> {
+  const result = await createLlamaCppMemoryEmbeddingProvider(
+    buildMemoryCreateOptions(options, options.dimensions),
+    runtimeOptions,
+  );
+  return {
+    provider: result.provider ? adaptMemoryEmbeddingProvider(result.provider) : null,
+    runtime: result.runtime,
+  };
+}
+
+function buildMemoryCreateOptions(
+  options: MemoryEmbeddingProviderCreateOptions | EmbeddingProviderCreateOptions,
+  outputDimensionality: number | undefined,
+): MemoryEmbeddingProviderCreateOptions {
+  const local = readLocalOptions(options);
+  const modelPath = normalizeOptionalString(local.modelPath) || DEFAULT_LLAMA_CPP_EMBEDDING_MODEL;
+  return {
+    config: options.config,
+    agentDir: options.agentDir,
+    provider: LLAMA_CPP_EMBEDDING_PROVIDER_ID,
+    fallback: "none",
+    remote: options.remote,
+    model: modelPath,
+    inputType: options.inputType,
+    queryInputType: options.queryInputType,
+    documentInputType: options.documentInputType,
+    local: {
+      ...local,
+      modelPath,
+    },
+    outputDimensionality,
+  };
+}
+
+function createLlamaCppEmbeddingProviderRuntime(identity: LlamaCppModelIdentity) {
+  return {
+    id: LLAMA_CPP_EMBEDDING_PROVIDER_ID,
+    inlineQueryTimeoutMs: 5 * 60_000,
+    inlineBatchTimeoutMs: 10 * 60_000,
+    cacheKeyData: identity.cacheKeyData,
+    ...(identity.aliases.length > 0 ? { indexIdentityAliases: identity.aliases } : {}),
+  };
+}
+
+export const llamaCppEmbeddingProviderAdapter: EmbeddingProviderAdapter = {
+  id: LLAMA_CPP_EMBEDDING_PROVIDER_ID,
+  defaultModel: DEFAULT_LLAMA_CPP_EMBEDDING_MODEL,
+  transport: "local",
+  formatSetupError: formatLlamaCppSetupError,
+  resolveIndexIdentity: (options) => {
+    const createOptions = buildMemoryCreateOptions(options, options.dimensions);
+    const local = readLocalOptions(createOptions);
+    return resolveLlamaCppModelIdentity(
+      local,
+      normalizeOptionalString(local.modelPath) ?? DEFAULT_LLAMA_CPP_EMBEDDING_MODEL,
+      createOptions.outputDimensionality,
+    );
+  },
+  create: async (options) => await createLlamaCppEmbeddingProviderResult(options),
+};