@synapcores/openclaw-memory 0.1.0

package/dist/index.js

@@ -0,0 +1,977 @@
+/**
+ * OpenClaw Memory (SynapCores) Plugin
+ *
+ * Long-term memory with vector search for AI conversations.
+ * Uses SynapCores AIDB for storage and OpenAI for embeddings.
+ * Provides seamless auto-recall and auto-capture via lifecycle hooks,
+ * plus three SynapCores-only extensions (SQL-filtered recall, graph-relation
+ * walks, and AutoML relevance scoring) — see `recallFiltered`,
+ * `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.
+ */
+import { Type } from "typebox";
+import { randomUUID } from "node:crypto";
+import OpenAI from "openai";
+import { stringEnum } from "openclaw/plugin-sdk";
+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();
+}
+/**
+ * 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.
+ */
+function unwrapEnvelope(raw) {
+    if (raw && typeof raw === "object" && "data" in raw) {
+        return raw.data;
+    }
+    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;
+    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) {
+            return;
+        }
+        if (this.initPromise) {
+            return this.initPromise;
+        }
+        this.initPromise = this.doInitialize();
+        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.
+        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);
+        }
+        catch {
+            // best-effort; fall through and try to create
+        }
+        if (!exists) {
+            try {
+                await this.http.post("/vectors/collections", {
+                    name: this.collectionName,
+                    dimensions: this.vectorDim,
+                    distance_metric: "cosine",
+                });
+            }
+            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)) {
+                        throw err;
+                    }
+                }
+                catch {
+                    throw err;
+                }
+            }
+        }
+        // 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);
+        }
+    }
+    async store(entry) {
+        await this.ensureInitialized();
+        const fullEntry = {
+            ...entry,
+            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,
+                    },
+                },
+            ],
+        });
+        return fullEntry;
+    }
+    async search(vector, limit = 5, minScore = 0.5) {
+        await this.ensureInitialized();
+        const result = await this.collection.vectorSearch({
+            vector,
+            field: "embedding",
+            topK: limit,
+            distanceMetric: "cosine",
+            includeMetadata: true,
+        });
+        const documents = (result.documents ?? []);
+        return documents.map(parseDocumentToResult).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.
+     */
+    async searchFiltered(vector, where, limit = 5) {
+        await this.ensureInitialized();
+        const result = await this.collection.vectorSearch({
+            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",
+            includeMetadata: true,
+        });
+        const documents = (result.documents ?? []);
+        return documents.map(parseDocumentToResult);
+    }
+    async delete(id) {
+        await this.ensureInitialized();
+        // Validate UUID format to prevent injection
+        const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+        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)}`);
+        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;
+    }
+    /** 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;
+        try {
+            raw = (await this.http.get(`/vectors/collections/${encodeURIComponent(this.collectionName)}/vectors/${encodeURIComponent(id)}`)).data;
+        }
+        catch (err) {
+            const e = err;
+            if (e?.code === "NOT_FOUND" || e?.status === 404)
+                return null;
+            throw err;
+        }
+        if (!raw)
+            return null;
+        const vec = unwrapEnvelope(raw);
+        if (!vec)
+            return null;
+        // Gateway response shape: { id, values: [...], metadata: { ... } }
+        const meta = vec.metadata ?? {};
+        return {
+            id: String(vec.id ?? id),
+            text: typeof meta.text === "string" ? meta.text : "",
+            vector: Array.isArray(vec.values) ? vec.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);
+    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,
+    };
+}
+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;
+    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),
+        score: similarity,
+    };
+}
+// ============================================================================
+// OpenAI Embeddings
+// ============================================================================
+class Embeddings {
+    model;
+    client;
+    constructor(apiKey, model) {
+        this.model = model;
+        this.client = new OpenAI({ apiKey });
+    }
+    async embed(text) {
+        const response = await this.client.embeddings.create({
+            model: this.model,
+            input: text,
+        });
+        return response.data[0].embedding;
+    }
+}
+// ============================================================================
+// Math helpers (shared between linker + relevance scorer)
+// ============================================================================
+function cosineSimilarity(a, b) {
+    let dot = 0;
+    let na = 0;
+    let nb = 0;
+    const len = Math.min(a.length, b.length);
+    for (let i = 0; i < len; i++) {
+        dot += a[i] * b[i];
+        na += a[i] * a[i];
+        nb += b[i] * b[i];
+    }
+    if (na === 0 || nb === 0)
+        return 0;
+    return dot / (Math.sqrt(na) * Math.sqrt(nb));
+}
+function ageDays(createdAt, now = Date.now()) {
+    return Math.max(0, (now - createdAt) / (1000 * 60 * 60 * 24));
+}
+const CATEGORY_INDEX = {
+    preference: 0,
+    fact: 1,
+    decision: 2,
+    entity: 3,
+    other: 4,
+};
+function categoryOneHot(category) {
+    const vec = [0, 0, 0, 0, 0];
+    vec[CATEGORY_INDEX[category] ?? 4] = 1;
+    return vec;
+}
+/**
+ * Feature vector used by both the heuristic relevance scorer and the
+ * AutoML training path. Keeping the layout in one place means
+ * `predictRelevance` and `trainRelevanceModel` always see the same shape.
+ */
+function buildRelevanceFeatures(queryVector, candidate, now = Date.now()) {
+    const cosine = cosineSimilarity(queryVector, candidate.vector);
+    const age = ageDays(candidate.createdAt, now);
+    const oneHot = categoryOneHot(candidate.category);
+    return {
+        cosine,
+        ageDays: age,
+        importance: candidate.importance,
+        category: candidate.category,
+        vector: [cosine, age, candidate.importance, ...oneHot],
+        asRecord: {
+            cosine,
+            age_days: age,
+            importance: candidate.importance,
+            category_preference: oneHot[0],
+            category_fact: oneHot[1],
+            category_decision: oneHot[2],
+            category_entity: oneHot[3],
+            category_other: oneHot[4],
+        },
+    };
+}
+// ============================================================================
+// Rule-based capture filter
+// ============================================================================
+const MEMORY_TRIGGERS = [
+    /zapamatuj si|pamatuj|remember/i,
+    /preferuji|radši|nechci|prefer/i,
+    /rozhodli jsme|budeme používat/i,
+    /\+\d{10,}/,
+    /[\w.-]+@[\w.-]+\.\w+/,
+    /můj\s+\w+\s+je|je\s+můj/i,
+    /my\s+\w+\s+is|is\s+my/i,
+    /i (like|prefer|hate|love|want|need)/i,
+    /always|never|important/i,
+];
+function shouldCapture(text) {
+    if (text.length < 10 || text.length > 500) {
+        return false;
+    }
+    // Skip injected context from memory recall
+    if (text.includes("<relevant-memories>")) {
+        return false;
+    }
+    // Skip system-generated content
+    if (text.startsWith("<") && text.includes("</")) {
+        return false;
+    }
+    // Skip agent summary responses (contain markdown formatting)
+    if (text.includes("**") && text.includes("\n-")) {
+        return false;
+    }
+    // Skip emoji-heavy responses (likely agent output)
+    const emojiCount = (text.match(/[\u{1F300}-\u{1F9FF}]/gu) || []).length;
+    if (emojiCount > 3) {
+        return false;
+    }
+    return MEMORY_TRIGGERS.some((r) => r.test(text));
+}
+function detectCategory(text) {
+    const lower = text.toLowerCase();
+    if (/prefer|radši|like|love|hate|want/i.test(lower)) {
+        return "preference";
+    }
+    if (/rozhodli|decided|will use|budeme/i.test(lower)) {
+        return "decision";
+    }
+    if (/\+\d{10,}|@[\w.-]+\.\w+|is called|jmenuje se/i.test(lower)) {
+        return "entity";
+    }
+    if (/is|are|has|have|je|má|jsou/i.test(lower)) {
+        return "fact";
+    }
+    return "other";
+}
+// ============================================================================
+// Cypher value escaping
+// ============================================================================
+/**
+ * Escape a string literal for safe inlining into a Cypher query.
+ *
+ * Gateway v1.6.5.2-ce explicitly rejects named-parameter bindings (`$param`)
+ * with HTTP 400; the supported path is to inline literal values into the
+ * query string. Memory IDs flow in from `randomUUID()` so they are normally
+ * safe, BUT we never trust upstream input — every string that ends up
+ * inside `'...'` in a Cypher fragment must go through this helper.
+ *
+ * Escapes single quotes (`'` -> `\'`) and backslashes (`\` -> `\\`).
+ * Returns the inner content only; callers are responsible for the
+ * surrounding quotes (so the helper is composable with template literals).
+ */
+export function escapeCypherString(value) {
+    return String(value).replace(/\\/g, "\\\\").replace(/'/g, "\\'");
+}
+// ============================================================================
+// Auto-link similar memories (capture-time graph edge creation)
+// ============================================================================
+// 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
+/**
+ * `linkSimilarMemories` is a no-op against gateway v1.6.5.x.
+ *
+ * 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:
+ *
+ *   `'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)
+ *
+ * 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.
+ */
+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;
+}
+// ============================================================================
+// SynapCores Extensions
+// ============================================================================
+const DEFAULT_RELEVANCE_MODEL = "openclaw_memory_relevance";
+const MIN_TRAINING_SAMPLES = 10;
+function relevanceModelName(workspace) {
+    return workspace ? `${DEFAULT_RELEVANCE_MODEL}_${workspace}` : DEFAULT_RELEVANCE_MODEL;
+}
+function createExtensions(db, embeddings, client, graphName, workspace, collectionName = DEFAULT_COLLECTION) {
+    const modelName = relevanceModelName(workspace);
+    async function modelExists(name) {
+        try {
+            const models = await client.automl.listModels();
+            return models.some((m) => m.name === name);
+        }
+        catch {
+            return false;
+        }
+    }
+    return {
+        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:
+            //
+            // 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.
+            //
+            // 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.");
+        },
+        async predictRelevance(query, candidates) {
+            if (candidates.length === 0)
+                return [];
+            const queryVector = await embeddings.embed(query);
+            const now = Date.now();
+            const features = candidates.map((c) => buildRelevanceFeatures(queryVector, c, now));
+            // Try model mode; on any failure (no model, transport error) fall
+            // back to the heuristic so the caller never gets an empty result.
+            if (await modelExists(modelName)) {
+                try {
+                    const model = await client.automl.getModel(modelName);
+                    const inputs = features.map((f) => f.asRecord);
+                    const raw = await model.predict(inputs);
+                    const preds = Array.isArray(raw) ? raw : [raw];
+                    return candidates.map((entry, i) => ({
+                        entry,
+                        relevance: clamp01(extractPrediction(preds[i])),
+                    }));
+                }
+                catch {
+                    // fall through to heuristic
+                }
+            }
+            // Heuristic mode (always available)
+            return candidates.map((entry, i) => {
+                const f = features[i];
+                const recency = Math.exp(-f.ageDays / 14);
+                const cosTerm = (f.cosine + 1) / 2; // map [-1, 1] -> [0, 1]
+                const score = 0.6 * cosTerm + 0.25 * recency + 0.15 * entry.importance;
+                return { entry, relevance: clamp01(score) };
+            });
+        },
+        async trainRelevanceModel(feedback) {
+            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.
+            //
+            // 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.");
+        },
+    };
+}
+function clamp01(n) {
+    if (!Number.isFinite(n))
+        return 0;
+    if (n < 0)
+        return 0;
+    if (n > 1)
+        return 1;
+    return n;
+}
+function extractPrediction(raw) {
+    if (typeof raw === "number")
+        return raw;
+    if (raw && typeof raw === "object") {
+        const r = raw;
+        if (typeof r.relevance === "number")
+            return r.relevance;
+        if (typeof r.prediction === "number")
+            return r.prediction;
+        if (typeof r.score === "number")
+            return r.score;
+        if (typeof r.value === "number")
+            return r.value;
+    }
+    return 0;
+}
+// ============================================================================
+// Plugin Definition
+// ============================================================================
+const memoryPlugin = {
+    id: "memory-synapcores",
+    name: "Memory (SynapCores)",
+    description: "SynapCores-backed long-term memory with auto-recall/capture, SQL filtering, graph relations, and AutoML relevance",
+    kind: "memory",
+    configSchema: memoryConfigSchema,
+    register(api) {
+        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 = {
+            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);
+        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);
+        const autoLinkSimilar = cfg.autoLinkSimilar !== false;
+        const graphName = cfg.graph;
+        api.logger.info(`memory-synapcores: plugin registered (host: ${cfg.synapcores.host}:${cfg.synapcores.port}, collection: ${collectionName}, autoLinkSimilar: ${autoLinkSimilar}, lazy init)`);
+        // ========================================================================
+        // Tools
+        // ========================================================================
+        api.registerTool({
+            name: "memory_recall",
+            label: "Memory Recall",
+            description: "Search through long-term memories. Use when you need context about user preferences, past decisions, or previously discussed topics.",
+            parameters: Type.Object({
+                query: Type.String({ description: "Search query" }),
+                limit: Type.Optional(Type.Number({ description: "Max results (default: 5)" })),
+            }),
+            async execute(_toolCallId, params) {
+                const { query, limit = 5 } = params;
+                const vector = await embeddings.embed(query);
+                const results = await db.search(vector, limit, 0.1);
+                if (results.length === 0) {
+                    return {
+                        content: [{ type: "text", text: "No relevant memories found." }],
+                        details: { count: 0 },
+                    };
+                }
+                const text = results
+                    .map((r, i) => `${i + 1}. [${r.entry.category}] ${r.entry.text} (${(r.score * 100).toFixed(0)}%)`)
+                    .join("\n");
+                // Strip vector data for serialization (typed arrays can't be cloned)
+                const sanitizedResults = results.map((r) => ({
+                    id: r.entry.id,
+                    text: r.entry.text,
+                    category: r.entry.category,
+                    importance: r.entry.importance,
+                    score: r.score,
+                }));
+                return {
+                    content: [{ type: "text", text: `Found ${results.length} memories:\n\n${text}` }],
+                    details: { count: results.length, memories: sanitizedResults },
+                };
+            },
+        }, { name: "memory_recall" });
+        api.registerTool({
+            name: "memory_store",
+            label: "Memory Store",
+            description: "Save important information in long-term memory. Use for preferences, facts, decisions.",
+            parameters: Type.Object({
+                text: Type.String({ description: "Information to remember" }),
+                importance: Type.Optional(Type.Number({ description: "Importance 0-1 (default: 0.7)" })),
+                category: Type.Optional(stringEnum(MEMORY_CATEGORIES)),
+            }),
+            async execute(_toolCallId, params) {
+                const { text, importance = 0.7, category = "other", } = params;
+                const vector = await embeddings.embed(text);
+                // Check for duplicates
+                const existing = await db.search(vector, 1, 0.95);
+                if (existing.length > 0) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `Similar memory already exists: "${existing[0].entry.text}"`,
+                            },
+                        ],
+                        details: {
+                            action: "duplicate",
+                            existingId: existing[0].entry.id,
+                            existingText: existing[0].entry.text,
+                        },
+                    };
+                }
+                const entry = await db.store({
+                    text,
+                    vector,
+                    importance,
+                    category,
+                });
+                // Best-effort auto-link to similar memories so `recallRelated`
+                // returns useful neighborhoods. Failures are swallowed and logged.
+                if (autoLinkSimilar) {
+                    await linkSimilarMemories(entry, db, client, graphName, api.logger);
+                }
+                return {
+                    content: [{ type: "text", text: `Stored: "${text.slice(0, 100)}..."` }],
+                    details: { action: "created", id: entry.id },
+                };
+            },
+        }, { name: "memory_store" });
+        api.registerTool({
+            name: "memory_forget",
+            label: "Memory Forget",
+            description: "Delete specific memories. GDPR-compliant.",
+            parameters: Type.Object({
+                query: Type.Optional(Type.String({ description: "Search to find memory" })),
+                memoryId: Type.Optional(Type.String({ description: "Specific memory ID" })),
+            }),
+            async execute(_toolCallId, params) {
+                const { query, memoryId } = params;
+                if (memoryId) {
+                    await db.delete(memoryId);
+                    return {
+                        content: [{ type: "text", text: `Memory ${memoryId} forgotten.` }],
+                        details: { action: "deleted", id: memoryId },
+                    };
+                }
+                if (query) {
+                    const vector = await embeddings.embed(query);
+                    const results = await db.search(vector, 5, 0.7);
+                    if (results.length === 0) {
+                        return {
+                            content: [{ type: "text", text: "No matching memories found." }],
+                            details: { found: 0 },
+                        };
+                    }
+                    if (results.length === 1 && results[0].score > 0.9) {
+                        await db.delete(results[0].entry.id);
+                        return {
+                            content: [{ type: "text", text: `Forgotten: "${results[0].entry.text}"` }],
+                            details: { action: "deleted", id: results[0].entry.id },
+                        };
+                    }
+                    const list = results
+                        .map((r) => `- [${r.entry.id.slice(0, 8)}] ${r.entry.text.slice(0, 60)}...`)
+                        .join("\n");
+                    // Strip vector data for serialization
+                    const sanitizedCandidates = results.map((r) => ({
+                        id: r.entry.id,
+                        text: r.entry.text,
+                        category: r.entry.category,
+                        score: r.score,
+                    }));
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `Found ${results.length} candidates. Specify memoryId:\n${list}`,
+                            },
+                        ],
+                        details: { action: "candidates", candidates: sanitizedCandidates },
+                    };
+                }
+                return {
+                    content: [{ type: "text", text: "Provide query or memoryId." }],
+                    details: { error: "missing_param" },
+                };
+            },
+        }, { name: "memory_forget" });
+        // ========================================================================
+        // CLI Commands
+        // ========================================================================
+        api.registerCli(({ program }) => {
+            const memory = program.command("ltm").description("SynapCores memory plugin commands");
+            memory
+                .command("list")
+                .description("List memories")
+                .action(async () => {
+                const count = await db.count();
+                console.log(`Total memories: ${count}`);
+            });
+            memory
+                .command("search")
+                .description("Search memories")
+                .argument("<query>", "Search query")
+                .option("--limit <n>", "Max results", "5")
+                .action(async (query, opts) => {
+                const vector = await embeddings.embed(query);
+                const results = await db.search(vector, parseInt(opts.limit), 0.3);
+                // Strip vectors for output
+                const output = results.map((r) => ({
+                    id: r.entry.id,
+                    text: r.entry.text,
+                    category: r.entry.category,
+                    importance: r.entry.importance,
+                    score: r.score,
+                }));
+                console.log(JSON.stringify(output, null, 2));
+            });
+            memory
+                .command("stats")
+                .description("Show memory statistics")
+                .action(async () => {
+                const count = await db.count();
+                console.log(`Total memories: ${count}`);
+            });
+        }, { commands: ["ltm"] });
+        // ========================================================================
+        // Lifecycle Hooks
+        // ========================================================================
+        // Auto-recall: inject relevant memories before agent starts
+        if (cfg.autoRecall) {
+            api.on("before_agent_start", async (event) => {
+                if (!event.prompt || event.prompt.length < 5) {
+                    return;
+                }
+                try {
+                    const vector = await embeddings.embed(event.prompt);
+                    const results = await db.search(vector, 3, 0.3);
+                    if (results.length === 0) {
+                        return;
+                    }
+                    const memoryContext = results
+                        .map((r) => `- [${r.entry.category}] ${r.entry.text}`)
+                        .join("\n");
+                    api.logger.info?.(`memory-synapcores: injecting ${results.length} memories into context`);
+                    return {
+                        prependContext: `<relevant-memories>\nThe following memories may be relevant to this conversation:\n${memoryContext}\n</relevant-memories>`,
+                    };
+                }
+                catch (err) {
+                    api.logger.warn(`memory-synapcores: recall failed: ${String(err)}`);
+                }
+            });
+        }
+        // Auto-capture: analyze and store important information after agent ends
+        if (cfg.autoCapture) {
+            api.on("agent_end", async (event) => {
+                if (!event.success || !event.messages || event.messages.length === 0) {
+                    return;
+                }
+                try {
+                    // Extract text content from messages (handling unknown[] type)
+                    const texts = [];
+                    for (const msg of event.messages) {
+                        // Type guard for message object
+                        if (!msg || typeof msg !== "object") {
+                            continue;
+                        }
+                        const msgObj = msg;
+                        // Only process user and assistant messages
+                        const role = msgObj.role;
+                        if (role !== "user" && role !== "assistant") {
+                            continue;
+                        }
+                        const content = msgObj.content;
+                        // Handle string content directly
+                        if (typeof content === "string") {
+                            texts.push(content);
+                            continue;
+                        }
+                        // Handle array content (content blocks)
+                        if (Array.isArray(content)) {
+                            for (const block of content) {
+                                if (block &&
+                                    typeof block === "object" &&
+                                    "type" in block &&
+                                    block.type === "text" &&
+                                    "text" in block &&
+                                    typeof block.text === "string") {
+                                    texts.push(block.text);
+                                }
+                            }
+                        }
+                    }
+                    // Filter for capturable content
+                    const toCapture = texts.filter((text) => text && shouldCapture(text));
+                    if (toCapture.length === 0) {
+                        return;
+                    }
+                    // Store each capturable piece (limit to 3 per conversation)
+                    let stored = 0;
+                    for (const text of toCapture.slice(0, 3)) {
+                        const category = detectCategory(text);
+                        const vector = await embeddings.embed(text);
+                        // Check for duplicates (high similarity threshold)
+                        const existing = await db.search(vector, 1, 0.95);
+                        if (existing.length > 0) {
+                            continue;
+                        }
+                        const entry = await db.store({
+                            text,
+                            vector,
+                            importance: 0.7,
+                            category,
+                        });
+                        if (autoLinkSimilar) {
+                            await linkSimilarMemories(entry, db, client, graphName, api.logger);
+                        }
+                        stored++;
+                    }
+                    if (stored > 0) {
+                        api.logger.info(`memory-synapcores: auto-captured ${stored} memories`);
+                    }
+                }
+                catch (err) {
+                    api.logger.warn(`memory-synapcores: capture failed: ${String(err)}`);
+                }
+            });
+        }
+        // ========================================================================
+        // Service
+        // ========================================================================
+        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})`);
+            },
+            stop: () => {
+                api.logger.info("memory-synapcores: stopped");
+            },
+        });
+        // ========================================================================
+        // SynapCores-only extensions
+        // ========================================================================
+        // 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;
+    },
+};
+export default memoryPlugin;
+//# sourceMappingURL=index.js.map