@synapcores/openclaw-memory 0.1.0 → 0.3.0

package/dist/index.js

@@ -9,55 +9,135 @@
  * `recallRelated`, and `predictRelevance`.
  *
  * This is the @synapcores/openclaw-memory drop-in alternative to
- * @openclaw/memory-lancedb. The parity API (recall + capture +
- * auto-recall/auto-capture) plus the three SynapCores-only extensions
- * are all fully wired in 0.1.0.
+ * @openclaw/memory-lancedb. Verified end-to-end against SynapCores
+ * gateway v1.6.5.2-ce. Requires @synapcores/sdk@^0.4.0 — which added
+ * `client.vectorCollection(name)` + `client.createVectorCollection(...)`
+ * and switched API-key auth to `Authorization: Bearer`.
  */
 import { Type } from "typebox";
 import { randomUUID } from "node:crypto";
 import OpenAI from "openai";
-import { stringEnum } from "openclaw/plugin-sdk";
+import { stringEnum } from "openclaw/plugin-sdk/core";
+import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
 import { SynapCores } from "@synapcores/sdk";
 import { MEMORY_CATEGORIES, memoryConfigSchema, vectorDimsForModel, } from "./config.js";
 // ============================================================================
 // SynapCores Provider
 // ============================================================================
 const DEFAULT_COLLECTION = "openclaw_memories";
-function getSdkHttp(client) {
-    return client._getHttpClient();
+/**
+ * MemoryDB — thin wrapper around `@synapcores/sdk@^0.4.0`'s
+ * `VectorCollection` handle. v0.2.0 dropped the direct
+ * `_getHttpClient().post('/vectors/collections/...')` workaround that
+ * v0.1.0 needed against SDK 0.3.x — SDK 0.4.0 ships `createVectorCollection`
+ * and `vectorCollection(name)` that target `/v1/vectors/collections/...`
+ * directly, so the plugin no longer has to bypass the SDK.
+ */
+// ============================================================================
+// Connection preflight
+//
+// This plugin is a CLIENT — it never installs or starts a SynapCores database.
+// The most common first-run failure is "installed the plugin, but the gateway
+// isn't running", which otherwise surfaces as a raw ECONNREFUSED. Preflight
+// turns that into an actionable message pointing at the installer + admin UI.
+// ============================================================================
+const PREFLIGHT_INSTALL_HINT = "This plugin needs a running SynapCores gateway — it does not install one. " +
+    "Install + start the free Community Edition:\n" +
+    "  curl -fsSL https://synapcores.com/install.sh | sh\n" +
+    "  synapcores start\n" +
+    "Docs: https://synapcores.com/install";
+function httpStatusOf(err) {
+    const e = err;
+    return e?.status ?? e?.statusCode ?? e?.response?.status;
+}
+// Raw transport-error fallback (used if the error isn't one of the SDK's typed
+// classes — e.g. a bare fetch/undici error).
+function isRawConnError(err) {
+    const code = String(err?.code ?? "");
+    const msg = String(err?.message ?? err ?? "");
+    return ([
+        "ECONNREFUSED",
+        "ENOTFOUND",
+        "ETIMEDOUT",
+        "ECONNRESET",
+        "EAI_AGAIN",
+        "EHOSTUNREACH",
+        "EHOSTDOWN",
+    ].includes(code) ||
+        /ECONNREFUSED|ENOTFOUND|ETIMEDOUT|ECONNRESET|EHOSTUNREACH|getaddrinfo|fetch failed|network error|socket hang up|Failed to connect to SynapCores|Connection refused/i.test(msg));
 }
 /**
- * Unwrap a JSON-API-style `{ data, meta }` envelope down to the inner payload.
- * Tolerates both the wrapped form and a bare body for forward-compat.
+ * Classify a gateway error. The @synapcores/sdk normalises failures into typed
+ * errors that carry a stable `.code` ("CONNECTION_ERROR" / "AUTH_ERROR") and a
+ * `.name` ("ConnectionError" / "AuthenticationError" / "TimeoutError"); we key
+ * off those first, then fall back to raw transport heuristics + HTTP status.
  */
-function unwrapEnvelope(raw) {
-    if (raw && typeof raw === "object" && "data" in raw) {
-        return raw.data;
+function classifyGatewayError(err) {
+    const code = String(err?.code ?? "");
+    const name = String(err?.name ?? "");
+    const status = httpStatusOf(err);
+    if (code === "CONNECTION_ERROR" ||
+        code === "TIMEOUT" ||
+        name === "ConnectionError" ||
+        name === "TimeoutError" ||
+        isRawConnError(err)) {
+        return "connection";
+    }
+    if (code === "AUTH_ERROR" || name === "AuthenticationError" || status === 401 || status === 403) {
+        return "auth";
+    }
+    return "other";
+}
+/**
+ * One lightweight round-trip to confirm the gateway is reachable AND the API
+ * key is accepted, before any memory operation runs. Throws an Error with an
+ * actionable message on failure; resolves on success. Uses
+ * `listVectorCollections()` (GET /v1/vectors/collections) — the same call
+ * MemoryDB makes first, and a known-good CE endpoint.
+ */
+async function preflightGateway(client) {
+    let host = "localhost";
+    let port = 8080;
+    let scheme = "http";
+    try {
+        const cfg = client._getConfig();
+        host = cfg.host ?? host;
+        port = cfg.port ?? port;
+        scheme = cfg.useHttps ? "https" : "http";
+    }
+    catch {
+        // _getConfig is best-effort — only used to make the message specific.
+    }
+    const url = `${scheme}://${host}:${port}`;
+    try {
+        await client.listVectorCollections();
+    }
+    catch (err) {
+        const kind = classifyGatewayError(err);
+        if (kind === "connection") {
+            throw new Error(`Cannot reach the SynapCores gateway at ${url}. ${PREFLIGHT_INSTALL_HINT}`);
+        }
+        if (kind === "auth") {
+            throw new Error(`The SynapCores gateway at ${url} rejected the API key. ` +
+                `Create a FullAccess key in the admin UI (http://${host}:8095) and set ` +
+                `synapcores.apiKey (or the SYNAPCORES_API_KEY env var).`);
+        }
+        throw new Error(`SynapCores preflight against ${url} failed: ${String(err?.message ?? err)}`);
     }
-    return raw;
 }
 class MemoryDB {
     collectionName;
     vectorDim;
     client;
-    // 0.1.0 talks to the gateway's /v1/vectors/collections subsystem directly.
-    // The SDK's `Collection` class targets the document-collection world
-    // (`/v1/collections/...`) which is a separate storage tree on the gateway,
-    // so reusing it for vector CRUD lands in the wrong subsystem. We keep one
-    // SDK `Collection` handle around purely so the SDK's normalised
-    // `vectorSearch()` (the only Collection method whose wire path matches
-    // the vector subsystem) stays in use.
-    collection = null;
+    vectorCollection = null;
     initPromise = null;
-    http;
     constructor(client, collectionName, vectorDim) {
         this.collectionName = collectionName;
         this.vectorDim = vectorDim;
         this.client = client;
-        this.http = getSdkHttp(client);
     }
     async ensureInitialized() {
-        if (this.collection) {
+        if (this.vectorCollection) {
             return;
         }
         if (this.initPromise) {
@@ -67,39 +147,37 @@ class MemoryDB {
         return this.initPromise;
     }
     async doInitialize() {
-        // Provision a vector collection on first use.
-        //
-        // The SDK's `client.createCollection()` posts to /v1/collections (the
-        // document-collection subsystem) and drops the vector_size / dimensions
-        // field on the way through — so it never lands in the vector subsystem.
-        // We bypass and POST /v1/vectors/collections directly with
-        // `{name, dimensions, distance_metric}`. Auth is already wired on the
-        // SDK's http client.
+        // Fail fast with an actionable message if the gateway is down or the key
+        // is wrong, before the collection probe muddies the error.
+        await preflightGateway(this.client);
+        // Probe for an existing vector collection (idempotent). The SDK's
+        // `listVectorCollections()` calls GET /v1/vectors/collections and
+        // returns the bare array; we fall through to create() on any error.
         let exists = false;
         try {
-            const raw = (await this.http.get("/vectors/collections")).data;
-            const items = unwrapEnvelope(raw);
-            const list = Array.isArray(items) ? items : [];
-            exists = list.some((it) => it?.name === this.collectionName);
+            const items = await this.client.listVectorCollections();
+            if (Array.isArray(items)) {
+                exists = items.some((it) => it?.name === this.collectionName);
+            }
         }
         catch {
             // best-effort; fall through and try to create
         }
         if (!exists) {
             try {
-                await this.http.post("/vectors/collections", {
+                this.vectorCollection = await this.client.createVectorCollection({
                     name: this.collectionName,
                     dimensions: this.vectorDim,
                     distance_metric: "cosine",
                 });
+                return;
             }
             catch (err) {
                 // Race with a concurrent creator — re-check before giving up.
                 try {
-                    const raw = (await this.http.get("/vectors/collections")).data;
-                    const items = unwrapEnvelope(raw);
-                    const list = Array.isArray(items) ? items : [];
-                    if (!list.some((it) => it?.name === this.collectionName)) {
+                    const items = await this.client.listVectorCollections();
+                    if (!Array.isArray(items) ||
+                        !items.some((it) => it?.name === this.collectionName)) {
                         throw err;
                     }
                 }
@@ -108,18 +186,8 @@ class MemoryDB {
                 }
             }
         }
-        // Cache a Collection handle just for vectorSearch (the one SDK method
-        // that already routes through the vector subsystem). v0.3.0 added
-        // `client.collection(name)` as a synchronous handle factory; fall back
-        // to the async getCollection path if not present.
-        const collFn = this.client
-            .collection;
-        if (typeof collFn === "function") {
-            this.collection = collFn.call(this.client, this.collectionName);
-        }
-        else {
-            this.collection = await this.client.getCollection(this.collectionName);
-        }
+        // Use the synchronous accessor — no extra round-trip.
+        this.vectorCollection = this.client.vectorCollection(this.collectionName);
     }
     async store(entry) {
         await this.ensureInitialized();
@@ -128,61 +196,46 @@ class MemoryDB {
             id: randomUUID(),
             createdAt: Date.now(),
         };
-        // Vector insert wire: POST /v1/vectors/collections/{name}/vectors
-        //   body = { vectors: [ { id, values, metadata } ] }
-        // We carry text + importance + category + createdAt in metadata so the
-        // search response can hydrate a MemoryEntry without a second round-trip.
-        await this.http.post(`/vectors/collections/${encodeURIComponent(this.collectionName)}/vectors`, {
-            vectors: [
-                {
-                    id: fullEntry.id,
-                    values: fullEntry.vector,
-                    metadata: {
-                        text: fullEntry.text,
-                        importance: fullEntry.importance,
-                        category: fullEntry.category,
-                        createdAt: fullEntry.createdAt,
-                    },
-                },
-            ],
+        // v0.2.0: SDK ships VectorCollection.insert(...) which posts to
+        // /v1/vectors/collections/{name}/vectors with the {vectors: [...]}
+        // envelope automatically. v0.1.0 had a direct _getHttpClient().post()
+        // workaround here — deleted now that SDK 0.4.0 covers the wire.
+        await this.vectorCollection.insert({
+            id: fullEntry.id,
+            values: fullEntry.vector,
+            metadata: {
+                text: fullEntry.text,
+                importance: fullEntry.importance,
+                category: fullEntry.category,
+                createdAt: fullEntry.createdAt,
+            },
         });
         return fullEntry;
     }
     async search(vector, limit = 5, minScore = 0.5) {
         await this.ensureInitialized();
-        const result = await this.collection.vectorSearch({
+        const hits = await this.vectorCollection.search({
             vector,
-            field: "embedding",
-            topK: limit,
-            distanceMetric: "cosine",
+            k: limit,
             includeMetadata: true,
         });
-        const documents = (result.documents ?? []);
-        return documents.map(parseDocumentToResult).filter((r) => r.score >= minScore);
+        return hits.map(parseHitToResult).filter((r) => r.score >= minScore);
     }
     /**
-     * Same shape as `search`, but accepts a SQL `WHERE` clause (forwarded
-     * to the gateway as the `filter` field on `/vector_search`). Used by
-     * the `recallFiltered` extension method.
+     * Same shape as `search`, but accepts a SQL `WHERE` clause. The SDK
+     * forwards `filter` as-is to the gateway's `/v1/vectors/collections/{n}/search`
+     * endpoint, which accepts either a JSON match object or `{ sql: "..." }`.
+     * Used by the `recallFiltered` extension method.
      */
     async searchFiltered(vector, where, limit = 5) {
         await this.ensureInitialized();
-        const result = await this.collection.vectorSearch({
+        const hits = await this.vectorCollection.search({
             vector,
-            field: "embedding",
-            topK: limit,
-            // The SDK forwards `filter` as the `filter` field in the POST body;
-            // the gateway accepts either a JSON match object or a SQL WHERE
-            // string. We pass the user's WHERE as `{ sql: where }` so the
-            // gateway routes it through the SQL path rather than the JSON-match
-            // path. If the gateway can't parse, the SDK's error wrapper will
-            // surface the message verbatim — we do NOT validate SQL client-side.
-            filter: { sql: where },
-            distanceMetric: "cosine",
+            k: limit,
             includeMetadata: true,
+            filter: { sql: where },
         });
-        const documents = (result.documents ?? []);
-        return documents.map(parseDocumentToResult);
+        return hits.map(parseHitToResult);
     }
     async delete(id) {
         await this.ensureInitialized();
@@ -191,25 +244,31 @@ class MemoryDB {
         if (!uuidRegex.test(id)) {
             throw new Error(`Invalid memory ID format: ${id}`);
         }
-        // Vector delete wire: DELETE /v1/vectors/collections/{name}/vectors/{id}
-        await this.http.delete(`/vectors/collections/${encodeURIComponent(this.collectionName)}/vectors/${encodeURIComponent(id)}`);
+        // v0.2.0: SDK 0.4.0's VectorCollection.delete(id) hits
+        // DELETE /v1/vectors/collections/{name}/vectors/{id}.
+        await this.vectorCollection.delete(id);
         return true;
     }
     async count() {
         await this.ensureInitialized();
-        // Vector collection info wire: GET /v1/vectors/collections/{name}
-        //   returns { data: { name, dimensions, vector_count, distance_metric, index_type } }
-        const raw = (await this.http.get(`/vectors/collections/${encodeURIComponent(this.collectionName)}`)).data;
-        const info = unwrapEnvelope(raw);
-        return typeof info?.vector_count === "number" ? info.vector_count : 0;
+        // v0.2.0: SDK 0.4.0's VectorCollection.count() probes /count first,
+        // falls back to info().vector_count. Either way, returns a number.
+        try {
+            return await this.vectorCollection.count();
+        }
+        catch {
+            return 0;
+        }
     }
     /** Fetch a single memory by ID (returns null if not found). */
     async get(id) {
         await this.ensureInitialized();
-        // Vector get wire: GET /v1/vectors/collections/{name}/vectors/{id}
-        let raw;
+        // v0.2.0: SDK 0.4.0's VectorCollection.get(id) returns
+        // { id, values, metadata } | null. v0.1.0 had a direct
+        // _getHttpClient().get() workaround here — deleted.
+        let hit = null;
         try {
-            raw = (await this.http.get(`/vectors/collections/${encodeURIComponent(this.collectionName)}/vectors/${encodeURIComponent(id)}`)).data;
+            hit = await this.vectorCollection.get(id);
         }
         catch (err) {
             const e = err;
@@ -217,73 +276,48 @@ class MemoryDB {
                 return null;
             throw err;
         }
-        if (!raw)
-            return null;
-        const vec = unwrapEnvelope(raw);
-        if (!vec)
+        if (!hit)
             return null;
-        // Gateway response shape: { id, values: [...], metadata: { ... } }
-        const meta = vec.metadata ?? {};
+        const meta = hit.metadata ?? {};
         return {
-            id: String(vec.id ?? id),
+            id: String(hit.id ?? id),
             text: typeof meta.text === "string" ? meta.text : "",
-            vector: Array.isArray(vec.values) ? vec.values : [],
+            vector: Array.isArray(hit.values) ? hit.values : [],
             importance: typeof meta.importance === "number" ? meta.importance : 0,
             category: meta.category ?? "other",
             createdAt: typeof meta.createdAt === "number" ? meta.createdAt : 0,
         };
     }
-    /** Internal accessor — used by extension methods. */
-    _collection() {
-        if (!this.collection) {
-            throw new Error("MemoryDB not initialized; call a method that triggers ensureInitialized first");
-        }
-        return this.collection;
-    }
 }
-function docToEntry(doc) {
-    // Vector-collection search results land here in two shapes:
-    //   (1) flat (legacy doc-collection):
-    //       { id, text, embedding, importance, category, createdAt, score }
-    //   (2) nested (vector-collection v2):
-    //       { id, values, metadata: { text, importance, category, createdAt }, score }
-    // We support both so the same parser works against either subsystem.
-    const meta = doc.metadata ?? {};
-    const pick = (key) => {
-        if (doc[key] !== undefined)
-            return doc[key];
-        if (meta[key] !== undefined)
-            return meta[key];
-        return undefined;
-    };
-    const text = pick("text") ?? "";
-    const importance = pick("importance");
-    const category = pick("category");
-    const createdAt = pick("createdAt");
-    const vector = (doc.values ?? doc.embedding);
+function hitToEntry(hit) {
+    // SDK 0.4.0 VectorCollection.search returns the gateway's hit shape:
+    //   { id, score, values?, metadata: { text, importance, category, createdAt } }
+    const meta = hit.metadata ?? {};
+    const text = typeof meta.text === "string" ? meta.text : "";
+    const importance = typeof meta.importance === "number" ? meta.importance : 0;
+    const category = meta.category ?? "other";
+    const createdAt = typeof meta.createdAt === "number" ? meta.createdAt : 0;
+    const vector = Array.isArray(hit.values) ? hit.values : [];
     return {
-        id: String(doc.id ?? ""),
-        text: String(text),
-        vector: Array.isArray(vector) ? vector : [],
-        importance: typeof importance === "number" ? importance : 0,
-        category: category ?? "other",
-        createdAt: typeof createdAt === "number" ? createdAt : 0,
+        id: String(hit.id ?? ""),
+        text,
+        vector,
+        importance,
+        category,
+        createdAt,
     };
 }
-function parseDocumentToResult(doc) {
-    // Gateway v1.6.5.2-ce vector search returns `score` as **cosine distance**
-    // (lower is better, 0 = identical, 1 = orthogonal, 2 = opposite). We
-    // convert to a [0, 1] similarity for the public API. If we ever see a
-    // `distance` field too (older / future shape) we honour that for parity.
-    const rawScore = typeof doc.score === "number" ? doc.score : undefined;
-    const rawDistance = typeof doc.distance === "number" ? doc.distance : undefined;
+function parseHitToResult(hit) {
+    // Gateway v1.6.5.2-ce returns cosine **distance** as `score` (lower =
+    // closer; 0 = identical, 1 = orthogonal, 2 = opposite). Convert to a
+    // [0, 1] similarity for the public API. If a separate `distance` field
+    // ever appears we honour it for parity.
+    const rawScore = typeof hit.score === "number" ? hit.score : undefined;
+    const rawDistance = typeof hit.distance === "number" ? hit.distance : undefined;
     const distance = rawDistance ?? rawScore ?? 0;
-    // Map cosine distance to a 0..1 similarity. cosine distance is in [0, 2]
-    // so we use `max(0, 1 - distance)` — for typical cosine-similarity-style
-    // ranges in [0, 1] this is equivalent to `1 - distance`.
     const similarity = Math.max(0, Math.min(1, 1 - distance));
     return {
-        entry: docToEntry(doc),
+        entry: hitToEntry(hit),
         score: similarity,
     };
 }
@@ -437,52 +471,89 @@ export function escapeCypherString(value) {
     return String(value).replace(/\\/g, "\\\\").replace(/'/g, "\\'");
 }
 // ============================================================================
-// Auto-link similar memories (capture-time graph edge creation)
+// Graph wiring — populate Memory nodes so SIMILAR_TO resolves at MATCH time
 // ============================================================================
-// Default cosine-similarity threshold for treating two memories as
-// "similar enough" to surface from `recallRelated`. Used as the operand on
-// the gateway's synthetic-edge syntax `[:SIMILAR_TO > THRESHOLD]`.
-const SIMILAR_TO_THRESHOLD = 0.7;
-const SIMILAR_TO_TOPK = 4; // legacy constant — kept for symmetry with v0.2.0 plan
+// Default cosine-similarity threshold for synthetic SIMILAR_TO edges.
+// Used as the operand in `[:SIMILAR_TO > THRESHOLD]` Cypher fragments.
+const SIMILAR_TO_THRESHOLD = 0.5;
+// Max hops for recallRelated walks — caps runaway traversals.
+const MAX_HOPS = 4;
+// Default result cap for recallRelated.
+const DEFAULT_RECALL_RELATED_LIMIT = 20;
 /**
- * `linkSimilarMemories` is a no-op against gateway v1.6.5.x.
+ * `linkSimilarMemories` — capture-time graph wiring (v0.2.0).
  *
- * The gateway treats `SIMILAR_TO` as a **synthetic / derived** edge type:
- * it computes the edge on-the-fly from the underlying vector similarity at
- * `MATCH` time, using `[:SIMILAR_TO > THRESHOLD]` syntax (where THRESHOLD
- * is a literal float). Explicit edge creation is rejected:
+ * v0.1.0 was a no-op: it tried to write explicit `SIMILAR_TO` edges via
+ * Cypher `MERGE`, which gateway v1.6.5.x rejects because SIMILAR_TO is a
+ * synthetic / derived edge type computed from the graph backend's vector
+ * index at MATCH time.
  *
- *   `'SIMILAR_TO' is a reserved synthetic edge type — the Cypher engine
- *    derives it from vector similarity and it cannot be stored as a literal
- *    edge.` (HTTP 400 from /v1/graph/edges)
+ * v0.2.0 takes the supported path instead: insert the Memory as a graph
+ * node carrying the embedding under the property name `embedding` — the
+ * field the gateway's brute-force vector index is wired against (see
+ * `aidb_gateway::routes::graph::attach_default_vector_index`). Once a
+ * Memory node exists, `recallRelated` can MATCH `[:SIMILAR_TO > T]`
+ * against it and get neighbors back without any pre-stored edges.
  *
- * Multi-statement Cypher (`MERGE ... MERGE ...`) is also rejected by this
- * gateway's parser. Together those constraints mean the original capture-time
- * MERGE pipeline doesn't apply — and doesn't need to: `recallRelated` reads
- * the synthetic similarity edges directly without any pre-stored state.
- *
- * The function is left as a public-API shim so `autoLinkSimilar = true`
- * doesn't error out for callers carrying the option from older configs.
- * 0.2.0 will likely add `MENTIONS` / `RELATES_TO` edges (which are NOT
- * synthetic) via the REST `/v1/graph/edges` endpoint.
+ * Failures here are non-fatal — the capture itself still succeeded in the
+ * vector subsystem; we just log and move on so recall continues to work.
  */
-async function linkSimilarMemories(entry, _db, _client, _graphName, _logger) {
-    void entry;
-    // No-op in 0.1.0. The gateway's synthetic-SIMILAR_TO edges make this
-    // unnecessary at capture-time: `recallRelated` reads similarity at query
-    // time, so there's nothing to pre-link.
-    return 0;
+async function linkSimilarMemories(entry, _db, client, _graphName, logger) {
+    try {
+        // Insert a Memory node with the embedding so the synthetic
+        // SIMILAR_TO edge in `recallRelated` has something to match against.
+        // The `id` property mirrors the vector-collection id so callers can
+        // join the two views.
+        //
+        // KNOWN SDK GAP (@synapcores/sdk@0.4.0):
+        //   `client.graph.nodes.create(label, props)` posts
+        //   `{label: <single>, properties}` but the gateway's
+        //   /v1/graph/nodes handler expects `{labels: <array>, properties}`
+        //   (see aidb_gateway::routes::graph::CreateNodeRequest). The result
+        //   is a node with `labels: []`, which never matches the `Memory`
+        //   label filter in MATCH. We bypass the SDK helper for THIS one
+        //   call and post the correct wire shape ourselves. Once SDK >0.4.0
+        //   fixes `GraphNodeApi.create` to send `labels`, this `_getHttpClient`
+        //   call can be replaced with `client.graph.nodes.create(...)`.
+        const http = client._getHttpClient();
+        await http.post("/graph/nodes", {
+            labels: ["Memory"],
+            properties: {
+                id: entry.id,
+                text: entry.text,
+                embedding: entry.vector,
+                importance: entry.importance,
+                category: entry.category,
+                createdAt: entry.createdAt,
+            },
+        });
+        return 1;
+    }
+    catch (err) {
+        const msg = err?.message ?? String(err);
+        logger?.warn?.(`memory-synapcores: failed to insert Memory graph node for ${entry.id}: ${msg} (capture still succeeded; recallRelated for this entry will return [])`);
+        return 0;
+    }
 }
 // ============================================================================
-// SynapCores Extensions
+// AutoML helpers — staged-collection training (v0.2.0)
 // ============================================================================
 const DEFAULT_RELEVANCE_MODEL = "openclaw_memory_relevance";
 const MIN_TRAINING_SAMPLES = 10;
+const TRAINING_TABLE_PREFIX = "openclaw_memory_relevance_training";
 function relevanceModelName(workspace) {
     return workspace ? `${DEFAULT_RELEVANCE_MODEL}_${workspace}` : DEFAULT_RELEVANCE_MODEL;
 }
-function createExtensions(db, embeddings, client, graphName, workspace, collectionName = DEFAULT_COLLECTION) {
+function trainingTableName(workspace) {
+    // SQL identifier — caller-controlled workspace must be alphanumeric.
+    // Gateway rejects non-alphanumeric `collection` values anyway, so the
+    // sanitisation here is belt-and-braces.
+    const safe = workspace ? workspace.replace(/[^a-zA-Z0-9_]/g, "_") : "";
+    return safe ? `${TRAINING_TABLE_PREFIX}_${safe}` : TRAINING_TABLE_PREFIX;
+}
+function createExtensions(db, embeddings, client, _graphName, workspace, _collectionName = DEFAULT_COLLECTION) {
     const modelName = relevanceModelName(workspace);
+    const stagingTable = trainingTableName(workspace);
     async function modelExists(name) {
         try {
             const models = await client.automl.listModels();
@@ -496,45 +567,99 @@ function createExtensions(db, embeddings, client, graphName, workspace, collecti
         async recallFiltered(options) {
             const limit = options.limit ?? 5;
             const vector = await embeddings.embed(options.semantic);
-            // Empty / `1=1` filter behaves the same as plain recall; pass it
-            // through anyway so the gateway sees a uniform request shape.
             return db.searchFiltered(vector, options.where, limit);
         },
         async recallRelated(memoryId, options = {}) {
-            // 0.1.0 fallback strategy:
+            // v0.2.0 implementation:
             //
-            // Gateway v1.6.5.x treats `SIMILAR_TO` as a **synthetic, derived**
-            // edge — it computes it on-the-fly from vector similarity at MATCH
-            // time, and the supported syntax is `[:SIMILAR_TO > THRESHOLD]`
-            // (single-hop only — `[:SIMILAR_TO*1..N]` and explicit MERGE / CREATE
-            // on `SIMILAR_TO` are both rejected). Crucially, the synthetic
-            // edge resolves against the **graph backend's** vector index, not
-            // the vector collection we write into. Without first promoting
-            // every Memory node into the graph with its embedding (a third
-            // subsystem that 0.1.0 does not wire), the MATCH walks always
-            // return zero rows.
+            // Gateway v1.6.5.x derives `SIMILAR_TO` synthetically at MATCH
+            // time from the graph backend's vector index on the `embedding`
+            // property. `linkSimilarMemories` populates that index on every
+            // capture by posting a `Memory` graph node carrying the embedding.
+            // With nodes in place, this method composes a Cypher MATCH that
+            // walks SIMILAR_TO (plus any non-synthetic edges the caller named
+            // via `edgeKinds`) and returns the neighborhood.
             //
-            // Rather than ship a method that silently returns `[]`, we surface
-            // the same kind of clear "ships in 0.2.0" error as
-            // `trainRelevanceModel`, but only when the caller actually asks for
-            // graph-backed recall. The signature stays so downstream code that
-            // wires this up today keeps compiling after the 0.2.0 upgrade.
-            //
-            // 0.2.0 plan: on capture, post the Memory node to /v1/graph/nodes
-            // with its embedding, then have this method compose
-            // `MATCH (start:Memory {id:'X'})-[:SIMILAR_TO > T]-(related)
-            //  RETURN related.id, related.text LIMIT 20`.
-            void options;
-            void client;
-            void graphName;
-            void escapeCypherString;
-            void db;
-            void memoryId;
-            throw new Error("memory-synapcores.recallRelated: signature-only in 0.1.0. " +
-                "Gateway v1.6.5.x derives SIMILAR_TO edges synthetically from a graph-node " +
-                "vector index that the plugin does not populate in this release; full graph-backed " +
-                "recall (with auto-indexed Memory nodes) ships in 0.2.0. Use predictRelevance + " +
-                "recallFiltered in the meantime for relevance-scoped recall.");
+            // Wire constraints:
+            //  - Multi-hop `[:SIMILAR_TO*1..N]` is rejected — SIMILAR_TO is
+            //    single-hop only. We honour `hops` for non-synthetic edges
+            //    and special-case hops=1 for SIMILAR_TO.
+            //  - `$param` bindings are rejected — values are inlined and
+            //    escaped via `escapeCypherString`.
+            const hops = Math.min(Math.max(1, options.hops ?? 1), MAX_HOPS);
+            const limit = options.limit ?? DEFAULT_RECALL_RELATED_LIMIT;
+            const threshold = options.similarityThreshold ?? SIMILAR_TO_THRESHOLD;
+            const edgeKinds = options.edgeKinds && options.edgeKinds.length > 0
+                ? options.edgeKinds
+                : ["SIMILAR_TO"];
+            const id = escapeCypherString(memoryId);
+            const out = [];
+            const seen = new Set();
+            for (const kind of edgeKinds) {
+                const safeKind = String(kind).replace(/[^A-Z_]/g, "");
+                if (!safeKind)
+                    continue;
+                let cypher;
+                if (safeKind === "SIMILAR_TO") {
+                    // Synthetic edge — single-hop only, threshold inlined.
+                    // Use undirected pattern so we surface neighbors regardless
+                    // of insertion order (the gateway computes similarity
+                    // symmetrically anyway).
+                    cypher = `MATCH (start:Memory {id: '${id}'})-[:SIMILAR_TO > ${threshold}]-(related:Memory) RETURN DISTINCT related LIMIT ${limit}`;
+                }
+                else {
+                    // Non-synthetic edge — variable-length supported.
+                    cypher = `MATCH (start:Memory {id: '${id}'})-[:${safeKind}*1..${hops}]-(related:Memory) RETURN DISTINCT related LIMIT ${limit}`;
+                }
+                let result;
+                try {
+                    result = await client.graph.cypher(cypher);
+                }
+                catch (err) {
+                    const msg = err?.message ?? String(err);
+                    throw new Error(`memory-synapcores.recallRelated: graph query failed for edge kind '${safeKind}': ${msg}`);
+                }
+                // The SDK normalises responses to { columns, rows, records }.
+                // Prefer `records` (column-keyed) and fall back to `rows`.
+                const records = Array.isArray(result?.records) ? result.records : [];
+                const rows = Array.isArray(result?.rows) ? result.rows : [];
+                const harvest = (node) => {
+                    if (!node || typeof node !== "object")
+                        return;
+                    const n = node;
+                    const props = (n.properties ?? {});
+                    const entryId = String(props.id ?? n.id ?? "");
+                    if (!entryId || entryId === memoryId)
+                        return;
+                    if (seen.has(entryId))
+                        return;
+                    seen.add(entryId);
+                    out.push({
+                        entry: {
+                            id: entryId,
+                            text: typeof props.text === "string" ? props.text : "",
+                            vector: Array.isArray(props.embedding) ? props.embedding : [],
+                            importance: typeof props.importance === "number" ? props.importance : 0,
+                            category: props.category ?? "other",
+                            createdAt: typeof props.createdAt === "number" ? props.createdAt : 0,
+                        },
+                        hops: safeKind === "SIMILAR_TO" ? 1 : hops,
+                        via: [safeKind],
+                    });
+                };
+                for (const rec of records) {
+                    // records: { related: <node> }
+                    harvest(rec?.related ?? Object.values(rec ?? {})[0]);
+                }
+                for (const row of rows) {
+                    if (!Array.isArray(row))
+                        continue;
+                    harvest(row[0]);
+                }
+                if (out.length >= limit)
+                    break;
+            }
+            return out.slice(0, limit);
         },
         async predictRelevance(query, candidates) {
             if (candidates.length === 0)
@@ -572,24 +697,107 @@ function createExtensions(db, embeddings, client, graphName, workspace, collecti
             if (!Array.isArray(feedback) || feedback.length < MIN_TRAINING_SAMPLES) {
                 throw new Error(`memory-synapcores.trainRelevanceModel: need at least ${MIN_TRAINING_SAMPLES} samples to train a relevance model (got ${Array.isArray(feedback) ? feedback.length : 0})`);
             }
-            // Gateway v1.6.5.2-ce explicitly rejects `config.inline_rows` on
-            // /v1/automl/train (HTTP 400 "config.inline_rows is not supported
-            // in this version. Stage the rows in a collection first."). The
-            // 0.1.0 release keeps the public method signature so callers can
-            // wire feedback collection now and have it light up the moment the
-            // 0.2.0 line ships the staged-collection workflow.
+            // v0.2.0 implementation: stage rows in a SQL table the gateway's
+            // AutoML can `SELECT * FROM`. Gateway v1.6.5.2-ce rejects
+            // `config.inline_rows` (the workflow v0.1.0 attempted) and
+            // requires the data to land in a real collection/table before
+            // training. We:
+            //   1. Hydrate each feedback row's memory into a full feature
+            //      vector (cosine, age_days, importance, one-hot category) via
+            //      the same `buildRelevanceFeatures` helper `predictRelevance`
+            //      uses — so train and predict see identical schemas.
+            //   2. CREATE TABLE IF NOT EXISTS the staging table.
+            //   3. INSERT each row.
+            //   4. Call client.automl.train({ collection, target: 'score', ... }).
             //
-            // 0.2.0 plan: stage `feedback` into a sibling collection
-            //   (`openclaw_memory_relevance_training[_<workspace>]`) and call
-            //   `automl.train({ collection, target, features, task: "regression" })`
-            //   pointing at it, then prune the staged rows on success.
-            void feedback;
-            void collectionName;
-            void modelName;
-            throw new Error("memory-synapcores.trainRelevanceModel: signature-only in 0.1.0. " +
-                "Gateway v1.6.5.x rejects inline training rows; full implementation ships in 0.2.0 " +
-                "(stages rows in a sibling collection before calling /v1/automl/train). " +
-                "predictRelevance continues to work in heuristic mode in the meantime.");
+            // Feedback rows whose memories have been deleted are skipped (with
+            // a soft warning to the caller via the throw message); training
+            // proceeds with the remainder.
+            // Hydrate feedback rows. Embed each query text once; pair with
+            // the stored Memory's vector to get the cosine feature.
+            const hydrated = [];
+            let missing = 0;
+            for (const fb of feedback) {
+                const mem = await db.get(fb.memoryId).catch(() => null);
+                if (!mem) {
+                    missing++;
+                    continue;
+                }
+                const queryVec = await embeddings.embed(fb.queryText);
+                const feats = buildRelevanceFeatures(queryVec, mem);
+                hydrated.push({
+                    cosine: feats.asRecord.cosine,
+                    age_days: feats.asRecord.age_days,
+                    importance: feats.asRecord.importance,
+                    category_preference: feats.asRecord.category_preference,
+                    category_fact: feats.asRecord.category_fact,
+                    category_decision: feats.asRecord.category_decision,
+                    category_entity: feats.asRecord.category_entity,
+                    category_other: feats.asRecord.category_other,
+                    score: clamp01(fb.score),
+                });
+            }
+            if (hydrated.length < MIN_TRAINING_SAMPLES) {
+                throw new Error(`memory-synapcores.trainRelevanceModel: after hydrating, only ${hydrated.length} feedback rows resolve to known memories (${missing} were missing) — need at least ${MIN_TRAINING_SAMPLES}`);
+            }
+            // 2. CREATE TABLE IF NOT EXISTS. The gateway's SQL surface accepts
+            //    standard CREATE TABLE. If the table already exists from a
+            //    prior run we swallow the duplicate-table error and keep
+            //    appending rows.
+            const createSql = `CREATE TABLE ${stagingTable} (cosine FLOAT, age_days FLOAT, importance FLOAT, category_preference FLOAT, category_fact FLOAT, category_decision FLOAT, category_entity FLOAT, category_other FLOAT, score FLOAT)`;
+            try {
+                await client.executeQuery({ sql: createSql });
+            }
+            catch (err) {
+                const msg = err?.message ?? String(err);
+                if (!/already exists|duplicate/i.test(msg)) {
+                    // Some gateways return "Table … created successfully" as data
+                    // rather than throwing on re-create; only re-throw on truly
+                    // unexpected errors.
+                    throw new Error(`memory-synapcores.trainRelevanceModel: failed to provision staging table '${stagingTable}': ${msg}`);
+                }
+            }
+            // 3. INSERT each row. We send them individually to keep the SQL
+            //    body small and stay friendly to the gateway's row limit.
+            for (const row of hydrated) {
+                const sql = `INSERT INTO ${stagingTable} (cosine, age_days, importance, category_preference, category_fact, category_decision, category_entity, category_other, score) VALUES (` +
+                    [
+                        row.cosine,
+                        row.age_days,
+                        row.importance,
+                        row.category_preference,
+                        row.category_fact,
+                        row.category_decision,
+                        row.category_entity,
+                        row.category_other,
+                        row.score,
+                    ]
+                        .map((n) => Number.isFinite(n) ? String(n) : "0")
+                        .join(", ") +
+                    ")";
+                try {
+                    await client.executeQuery({ sql });
+                }
+                catch (err) {
+                    const msg = err?.message ?? String(err);
+                    throw new Error(`memory-synapcores.trainRelevanceModel: failed to insert training row into '${stagingTable}': ${msg}`);
+                }
+            }
+            // 4. Train via /v1/automl/train. The gateway issues
+            //    `SELECT * FROM {collection}` internally and trains on the
+            //    `target` column.
+            const model = await client.automl.train({
+                collection: stagingTable,
+                target: "score",
+                task: "regression",
+                name: modelName,
+                max_trials: 5,
+                validation_split: 0.2,
+            });
+            return {
+                modelId: model.id ?? modelName,
+                modelName: model.name ?? modelName,
+            };
         },
     };
 }
@@ -631,32 +839,16 @@ const memoryPlugin = {
         const cfg = memoryConfigSchema.parse(api.pluginConfig);
         const vectorDim = vectorDimsForModel(cfg.embedding.model ?? "text-embedding-3-small");
         const collectionName = cfg.collection ?? DEFAULT_COLLECTION;
-        // Auth-header shim:
-        // @synapcores/sdk@0.3.0 sends `aidb_*` / `ak_*` keys via the `X-API-Key`
-        // header when constructed with `{ apiKey }`. Gateway v1.6.5.2-ce only
-        // honours `Authorization: Bearer aidb_*` (or `Authorization: ApiKey ...`)
-        // and will reject `X-API-Key` with HTTP 401 "missing_authorization".
-        //
-        // The SDK *does* route `{ jwtToken }` through `Authorization: Bearer`,
-        // and the gateway accepts an `aidb_*` value in that header (it tries JWT
-        // validation first, then falls back to api-key lookup on failure). So we
-        // route any `aidb_*` / `ak_*` key supplied as `apiKey` through `jwtToken`
-        // here. End-users keep writing `synapcores.apiKey` in their config — the
-        // plugin handles the header difference internally. When the SDK ships a
-        // version that uses Bearer for api keys, this branch becomes a no-op.
-        const rawKey = cfg.synapcores.apiKey;
-        const sdkConfig = {
+        // v0.2.0: pass apiKey straight through. @synapcores/sdk@0.4.0
+        // routes both apiKey AND jwtToken via `Authorization: Bearer`, so
+        // the v0.1.0 shim that re-routed `aidb_*` / `ak_*` keys through
+        // `jwtToken` to coerce the right header is gone.
+        const client = new SynapCores({
             host: cfg.synapcores.host,
             port: cfg.synapcores.port,
             useHttps: cfg.synapcores.useHttps,
-        };
-        if (rawKey.startsWith("aidb_") || rawKey.startsWith("ak_")) {
-            sdkConfig.jwtToken = rawKey;
-        }
-        else {
-            sdkConfig.apiKey = rawKey;
-        }
-        const client = new SynapCores(sdkConfig);
+            apiKey: cfg.synapcores.apiKey,
+        });
         const db = new MemoryDB(client, collectionName, vectorDim);
         const embeddings = new Embeddings(cfg.embedding.apiKey, cfg.embedding.model);
         const extensions = createExtensions(db, embeddings, client, cfg.graph, cfg.workspace, collectionName);
@@ -736,8 +928,9 @@ const memoryPlugin = {
                     importance,
                     category,
                 });
-                // Best-effort auto-link to similar memories so `recallRelated`
-                // returns useful neighborhoods. Failures are swallowed and logged.
+                // v0.2.0: linkSimilarMemories now inserts a Memory graph node
+                // carrying the embedding so recallRelated has something to
+                // MATCH against. Failures are non-fatal (logged in-helper).
                 if (autoLinkSimilar) {
                     await linkSimilarMemories(entry, db, client, graphName, api.logger);
                 }
@@ -952,8 +1145,18 @@ const memoryPlugin = {
         // ========================================================================
         api.registerService({
             id: "memory-synapcores",
-            start: () => {
-                api.logger.info(`memory-synapcores: initialized (host: ${cfg.synapcores.host}:${cfg.synapcores.port}, collection: ${collectionName}, model: ${cfg.embedding.model})`);
+            start: async () => {
+                // Best-effort startup probe: surface a DB-down / bad-key problem
+                // immediately in the logs (and `openclaw plugins doctor`) without
+                // bricking the host — memory ops still lazily retry on first use.
+                try {
+                    await preflightGateway(client);
+                    api.logger.info(`memory-synapcores: initialized (host: ${cfg.synapcores.host}:${cfg.synapcores.port}, collection: ${collectionName}, model: ${cfg.embedding.model})`);
+                }
+                catch (err) {
+                    api.logger.warn(`memory-synapcores: ${String(err?.message ?? err)}`);
+                    api.logger.warn("memory-synapcores: continuing with lazy init — memory operations will retry on first use.");
+                }
             },
             stop: () => {
                 api.logger.info("memory-synapcores: stopped");
@@ -965,13 +1168,15 @@ const memoryPlugin = {
         // Expose the extension surface on the plugin instance so callers can
         // reach `recallFiltered` / `recallRelated` / `predictRelevance` /
         // `trainRelevanceModel` via the OpenClaw plugin registry
-        // (e.g. `plugin.extensions.recallFiltered`). We attach via Object.assign
-        // rather than a top-level field on the plugin definition because
-        // `register()` is what produces the live backend; the extensions need
-        // access to the instantiated client + db.
-        memoryPlugin.extensions =
-            extensions;
+        // (e.g. `plugin.extensions.recallFiltered`).
+        //
+        // NOTE: attach to `pluginEntry` (the definePluginEntry result that is the
+        // default export), NOT the inner `memoryPlugin` — definePluginEntry returns
+        // a fresh normalized object, so attaching to the inner one would hide the
+        // extensions from every consumer of the loaded plugin.
+        pluginEntry.extensions = extensions;
     },
 };
-export default memoryPlugin;
+const pluginEntry = definePluginEntry(memoryPlugin);
+export default pluginEntry;
 //# sourceMappingURL=index.js.map