docs: document memory remote helpers

packages/memory-host-sdk/src/host/embedding-provider-adapter-utils.ts

@@ -1,9 +1,13 @@
 import { normalizeLowercaseStringOrEmpty } from "./string-utils.js";
 
+// Adapter helpers shared by remote embedding provider implementations.
+
+/** Detect missing API key errors from provider auth resolution. */
 export function isMissingEmbeddingApiKeyError(err: unknown): boolean {
   return err instanceof Error && err.message.includes("No API key found for provider");
 }
 
+/** Return stable cache headers after removing provider-specific secret headers. */
 export function sanitizeEmbeddingCacheHeaders(
   headers: Record<string, string>,
   excludedHeaderNames: string[],
@@ -17,6 +21,7 @@ export function sanitizeEmbeddingCacheHeaders(
     .map(([key, value]) => [key, value]);
 }
 
+/** Convert custom-id keyed batch embeddings back to request-index order. */
 export function mapBatchEmbeddingsByIndex(
   byCustomId: Map<string, number[]>,
   count: number,

packages/memory-host-sdk/src/host/embeddings-debug.ts

@@ -1,7 +1,10 @@
 import { normalizeLowercaseStringOrEmpty } from "./string-utils.js";
 
+// Lightweight stderr debug logging for memory embedding internals.
+
 const debugEmbeddings = isTruthyEnvValue(process.env.OPENCLAW_DEBUG_MEMORY_EMBEDDINGS);
 
+/** Write embedding debug metadata when OPENCLAW_DEBUG_MEMORY_EMBEDDINGS is enabled. */
 export function debugEmbeddingsLog(message: string, meta?: Record<string, unknown>): void {
   if (!debugEmbeddings) {
     return;
@@ -10,6 +13,7 @@ export function debugEmbeddingsLog(message: string, meta?: Record<string, unknow
   process.stderr.write(`${message}${suffix}\n`);
 }
 
+/** Parse common truthy env values for debug toggles. */
 function isTruthyEnvValue(value?: string): boolean {
   switch (normalizeLowercaseStringOrEmpty(value)) {
     case "1":

packages/memory-host-sdk/src/host/embeddings-remote-client.ts

@@ -5,8 +5,12 @@ import { resolveMemorySecretInputString } from "./secret-input.js";
 import type { SsrFPolicy } from "./ssrf-policy.js";
 import { normalizeOptionalString } from "./string-utils.js";
 
+// Builds authenticated remote embedding HTTP clients from agent memory config.
+
+/** Provider id used for remote embedding auth and config lookup. */
 export type RemoteEmbeddingProviderId = string;
 
+/** Attribution headers for native OpenAI embedding calls. */
 function resolveOpenClawAttributionHeaders(): Record<string, string> {
   const version = typeof process !== "undefined" ? process.env.OPENCLAW_VERSION?.trim() : undefined;
   return {
@@ -16,6 +20,7 @@ function resolveOpenClawAttributionHeaders(): Record<string, string> {
   };
 }
 
+/** Detect the native OpenAI embeddings API route that accepts attribution headers. */
 function isNativeOpenAIEmbeddingRoute(provider: string, baseUrl: string): boolean {
   if (provider !== "openai") {
     return false;
@@ -27,6 +32,7 @@ function isNativeOpenAIEmbeddingRoute(provider: string, baseUrl: string): boolea
   }
 }
 
+/** Resolve base URL, bearer headers, header overrides, and SSRF policy for remote embeddings. */
 export async function resolveRemoteEmbeddingBearerClient(params: {
   provider: RemoteEmbeddingProviderId;
   options: EmbeddingProviderOptions;

packages/memory-host-sdk/src/host/embeddings-remote-fetch.ts

@@ -1,16 +1,21 @@
 import { postJson } from "./post-json.js";
 import type { SsrFPolicy } from "./ssrf-policy.js";
 
+// Fetches and validates OpenAI-compatible embedding responses.
+
+/** Narrow unknown JSON payloads to plain objects. */
 function asRecord(value: unknown): Record<string, unknown> | undefined {
   return typeof value === "object" && value !== null && !Array.isArray(value)
     ? (value as Record<string, unknown>)
     : undefined;
 }
 
+/** Build the common malformed embedding response error. */
 function malformedEmbeddingResponse(errorPrefix: string): Error {
   return new Error(`${errorPrefix}: malformed JSON response`);
 }
 
+/** Validate and return one finite embedding vector. */
 function readEmbeddingVector(value: unknown, errorPrefix: string): number[] {
   if (!Array.isArray(value)) {
     throw malformedEmbeddingResponse(errorPrefix);
@@ -23,11 +28,13 @@ function readEmbeddingVector(value: unknown, errorPrefix: string): number[] {
   return value;
 }
 
+/** Resolve expected response count from the request body when input is an array. */
 function resolveExpectedEmbeddingCount(body: unknown): number | undefined {
   const input = asRecord(body)?.input;
   return Array.isArray(input) ? input.length : undefined;
 }
 
+/** POST an embedding request and return validated vectors in provider response order. */
 export async function fetchRemoteEmbeddingVectors(params: {
   url: string;
   headers: Record<string, string>;

packages/memory-host-sdk/src/host/embeddings-remote-provider.ts

@@ -6,6 +6,9 @@ import { fetchRemoteEmbeddingVectors } from "./embeddings-remote-fetch.js";
 import type { EmbeddingProvider, EmbeddingProviderOptions } from "./embeddings.types.js";
 import type { SsrFPolicy } from "./ssrf-policy.js";
 
+// Remote embedding provider factory for OpenAI-compatible embeddings APIs.
+
+/** HTTP client details required by a remote embedding provider. */
 export type RemoteEmbeddingClient = {
   baseUrl: string;
   headers: Record<string, string>;
@@ -14,6 +17,7 @@ export type RemoteEmbeddingClient = {
   model: string;
 };
 
+/** Create an EmbeddingProvider backed by a remote embeddings endpoint. */
 export function createRemoteEmbeddingProvider(params: {
   id: string;
   client: RemoteEmbeddingClient;
@@ -50,6 +54,7 @@ export function createRemoteEmbeddingProvider(params: {
   };
 }
 
+/** Resolve a normalized remote embedding client from provider config and model options. */
 export async function resolveRemoteEmbeddingClient(params: {
   provider: RemoteEmbeddingProviderId;
   options: EmbeddingProviderOptions;

packages/memory-host-sdk/src/host/post-json.ts

@@ -2,6 +2,9 @@ import { withRemoteHttpResponse } from "./remote-http.js";
 import { readResponseJsonWithLimit, readResponseTextSnippet } from "./response-snippet.js";
 import type { SsrFPolicy } from "./ssrf-policy.js";
 
+// Shared JSON POST helper for guarded remote memory provider calls.
+
+/** POST JSON, parse bounded response JSON, and attach status metadata when requested. */
 export async function postJson<T>(params: {
   url: string;
   headers: Record<string, string>;

packages/memory-host-sdk/src/host/remote-http.ts

@@ -5,11 +5,16 @@ import {
 } from "./openclaw-runtime-network.js";
 import type { SsrFPolicy } from "./ssrf-policy.js";
 
+// Remote memory HTTP wrapper that applies SSRF policy and releases guarded sockets.
+
+/** Proxy mode used only for URLs that the runtime classified as env-proxy safe. */
 export const MEMORY_REMOTE_TRUSTED_ENV_PROXY_MODE = "trusted_env_proxy";
 
+/** Build an SSRF allow policy from a configured remote base URL. */
 export const buildRemoteBaseUrlPolicy: (baseUrl: string) => SsrFPolicy | undefined =
   ssrfPolicyFromHttpBaseUrlAllowedHostname;
 
+/** Execute a remote HTTP request under SSRF guard and always release the response handle. */
 export async function withRemoteHttpResponse<T>(params: {
   url: string;
   init?: RequestInit;

packages/memory-host-sdk/src/host/ssrf-policy.ts

@@ -1,3 +1,6 @@
+// Public SSRF policy shape accepted by memory host remote HTTP helpers.
+
+/** Host/network allowlist policy forwarded to the runtime SSRF guard. */
 export type SsrFPolicy = {
   allowPrivateNetwork?: boolean;
   dangerouslyAllowPrivateNetwork?: boolean;