@synapcores/openclaw-memory 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,241 @@
+/**
+ * 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 { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { type MemoryCategory } from "./config.js";
+export type MemoryEntry = {
+    id: string;
+    text: string;
+    vector: number[];
+    importance: number;
+    category: MemoryCategory;
+    createdAt: number;
+};
+export type MemorySearchResult = {
+    entry: MemoryEntry;
+    score: number;
+};
+/**
+ * Options for `recallFiltered`: a SynapCores-only extension that pairs a
+ * semantic vector search with a SQL `WHERE` clause (date ranges, tags,
+ * importance thresholds, category equality, etc.).
+ */
+export type RecallFilteredOptions = {
+    /** SQL fragment applied as the search filter (e.g. `category = 'preference' AND importance >= 0.7`). */
+    where: string;
+    /** Natural-language query that gets embedded and used as the search vector. */
+    semantic: string;
+    /** Maximum results to return (default: 5). */
+    limit?: number;
+};
+/**
+ * Options for `recallRelated`: a SynapCores-only extension that walks the
+ * memory graph from a given memory ID and returns the neighborhood.
+ */
+export type RecallRelatedOptions = {
+    /** Maximum graph hops to traverse (default: 1). */
+    hops?: number;
+    /** Restrict to specific edge kinds (default: any). Common kinds: `SIMILAR_TO`, `MENTIONS`, `RELATES_TO`. */
+    edgeKinds?: string[];
+};
+/**
+ * One result returned from `recallRelated` — the neighbor memory plus the
+ * shortest path length (hops) from the source memory.
+ */
+export type RelatedMemoryResult = {
+    entry: MemoryEntry;
+    hops: number;
+    via: string[];
+};
+/**
+ * One result returned from `predictRelevance` — the candidate memory plus
+ * a model-predicted relevance score in [0, 1].
+ */
+export type RelevanceScoredMemory = {
+    entry: MemoryEntry;
+    /** Predicted relevance score in [0, 1]. */
+    relevance: number;
+};
+/**
+ * One labelled training sample for `trainRelevanceModel`.
+ */
+export type RelevanceFeedback = {
+    /** UUID of the memory the user actually engaged with (or didn't). */
+    memoryId: string;
+    /** Natural-language query the user issued. */
+    queryText: string;
+    /** Engagement score in [0, 1] (1 = highly relevant, 0 = not relevant). */
+    score: number;
+};
+/**
+ * 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 declare function escapeCypherString(value: string): string;
+/**
+ * Build the runtime extension surface exposed on the plugin instance. These
+ * methods are exported via `memoryPlugin.extensions` so callers can reach
+ * them through the OpenClaw plugin registry.
+ *
+ * The three SynapCores-only methods use:
+ *   - `client.collection(...).vectorSearch({ ..., filter })` for recallFiltered,
+ *     forwarding the SQL `WHERE` clause through to the gateway under
+ *     `filter: { sql: where }`.
+ *   - `client.graph.cypher(...)` for recallRelated, walking the `SIMILAR_TO`
+ *     edges created automatically at capture-time (plus any `MENTIONS` /
+ *     `RELATES_TO` edges added by future entity-extraction tools).
+ *   - `client.automl.getModel(...).predict(...)` for predictRelevance, with
+ *     a deterministic heuristic fallback when no model is trained yet.
+ */
+export interface MemorySynapCoresExtensions {
+    /**
+     * Vector recall scoped by a SQL `WHERE` clause.
+     *
+     * @example
+     *   await ext.recallFiltered({
+     *     where: "category = 'preference' AND importance >= 0.7 AND createdAt > 1700000000000",
+     *     semantic: "what kind of UI does the user prefer?",
+     *     limit: 5,
+     *   });
+     */
+    recallFiltered(options: RecallFilteredOptions): Promise<MemorySearchResult[]>;
+    /**
+     * Graph walk from a memory through `SIMILAR_TO` / `MENTIONS` / `RELATES_TO`
+     * edges, returning the neighborhood.
+     *
+     * @param memoryId - UUID of the source memory.
+     * @param options - Hops and edge-kind filter.
+     *
+     * @remarks `SIMILAR_TO` edges are auto-created at capture time when
+     * `autoLinkSimilar` is true (default). `via` is left empty in 0.1.0;
+     * derive it from a follow-up Cypher walk if you need the full path.
+     */
+    recallRelated(memoryId: string, options?: RecallRelatedOptions): Promise<RelatedMemoryResult[]>;
+    /**
+     * Score candidate memories against a query.
+     *
+     * Two execution modes:
+     *  - **Model mode**: if an AutoML model named
+     *    `openclaw_memory_relevance[_<workspace>]` exists, the candidates'
+     *    feature vectors are passed through `model.predict()`.
+     *  - **Heuristic mode** (default fallback): `relevance = 0.6 * cosine +
+     *    0.25 * exp(-age_days/14) + 0.15 * importance`.
+     *
+     * Train the model with `trainRelevanceModel(feedback)` to switch to model
+     * mode automatically on the next call.
+     *
+     * @param query - The user query / agent prompt to score relevance against.
+     * @param candidates - Memories to score (typically the top-K of a recall).
+     * @returns Candidates with a `relevance` score in [0, 1], not re-sorted.
+     */
+    predictRelevance(query: string, candidates: MemoryEntry[]): Promise<RelevanceScoredMemory[]>;
+    /**
+     * Train (or retrain) the AutoML model used by `predictRelevance`.
+     *
+     * @param feedback - Array of `{ memoryId, queryText, score }` samples.
+     *                   Requires at least {@link MIN_TRAINING_SAMPLES} samples;
+     *                   throws otherwise.
+     * @returns The id of the trained model.
+     */
+    trainRelevanceModel(feedback: RelevanceFeedback[]): Promise<{
+        modelId: string;
+        modelName: string;
+    }>;
+}
+declare const memoryPlugin: {
+    id: string;
+    name: string;
+    description: string;
+    kind: "memory";
+    configSchema: {
+        parse(value: unknown): import("./config.js").MemoryConfig;
+        uiHints: {
+            "embedding.apiKey": {
+                label: string;
+                sensitive: boolean;
+                placeholder: string;
+                help: string;
+            };
+            "embedding.model": {
+                label: string;
+                placeholder: string;
+                help: string;
+            };
+            "synapcores.host": {
+                label: string;
+                placeholder: string;
+                help: string;
+            };
+            "synapcores.port": {
+                label: string;
+                placeholder: string;
+                help: string;
+            };
+            "synapcores.apiKey": {
+                label: string;
+                sensitive: boolean;
+                placeholder: string;
+                help: string;
+            };
+            "synapcores.useHttps": {
+                label: string;
+                advanced: boolean;
+                help: string;
+            };
+            collection: {
+                label: string;
+                placeholder: string;
+                advanced: boolean;
+                help: string;
+            };
+            graph: {
+                label: string;
+                placeholder: string;
+                advanced: boolean;
+                help: string;
+            };
+            autoCapture: {
+                label: string;
+                help: string;
+            };
+            autoRecall: {
+                label: string;
+                help: string;
+            };
+            autoLinkSimilar: {
+                label: string;
+                advanced: boolean;
+                help: string;
+            };
+            workspace: {
+                label: string;
+                advanced: boolean;
+                help: string;
+            };
+        };
+    };
+    register(api: OpenClawPluginApi): void;
+};
+export default memoryPlugin;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAO7D,OAAO,EAEL,KAAK,cAAc,EAGpB,MAAM,aAAa,CAAC;AAMrB,MAAM,MAAM,WAAW,GAAG;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,cAAc,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,KAAK,EAAE,WAAW,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,qBAAqB,GAAG;IAClC,wGAAwG;IACxG,KAAK,EAAE,MAAM,CAAC;IACd,+EAA+E;IAC/E,QAAQ,EAAE,MAAM,CAAC;IACjB,8CAA8C;IAC9C,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,oBAAoB,GAAG;IACjC,mDAAmD;IACnD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,4GAA4G;IAC5G,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC,KAAK,EAAE,WAAW,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,EAAE,CAAC;CACf,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,qBAAqB,GAAG;IAClC,KAAK,EAAE,WAAW,CAAC;IACnB,2CAA2C;IAC3C,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,qEAAqE;IACrE,QAAQ,EAAE,MAAM,CAAC;IACjB,8CAA8C;IAC9C,SAAS,EAAE,MAAM,CAAC;IAClB,0EAA0E;IAC1E,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAodF;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAExD;AA2DD;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,0BAA0B;IACzC;;;;;;;;;OASG;IACH,cAAc,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAAC;IAE9E;;;;;;;;;;OAUG;IACH,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,oBAAoB,GAAG,OAAO,CAAC,mBAAmB,EAAE,CAAC,CAAC;IAEhG;;;;;;;;;;;;;;;;OAgBG;IACH,gBAAgB,CACd,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,WAAW,EAAE,GACxB,OAAO,CAAC,qBAAqB,EAAE,CAAC,CAAC;IAEpC;;;;;;;OAOG;IACH,mBAAmB,CAAC,QAAQ,EAAE,iBAAiB,EAAE,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACrG;AAsKD,QAAA,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAOF,iBAAiB;CAqbhC,CAAC;AAEF,eAAe,YAAY,CAAC"}