@synapcores/openclaw-memory 0.3.0 → 0.4.0

package/README.md

@@ -1,12 +1,26 @@
 # @synapcores/openclaw-memory
 
-A long-term memory plugin for [OpenClaw](https://github.com/openclaw/openclaw) that uses **SynapCores AIDB** as the storage backend. Drop-in alternative to `@openclaw/memory-lancedb` with the same auto-recall / auto-capture lifecycle, plus three SynapCores-only extensions: SQL-filtered semantic recall, graph-relation walks, and AutoML relevance scoring.
+A long-term memory plugin for [OpenClaw](https://github.com/openclaw/openclaw) that uses **SynapCores AIDB** as the storage backend. Drop-in alternative to `@openclaw/memory-lancedb` with the same auto-recall / auto-capture lifecycle, plus four SynapCores-only extensions: SQL-filtered semantic recall, graph-relation walks, AutoML relevance scoring, and a model-training helper.
 
-> **0.2.0 shipping note:** verified against gateway `v1.6.5.2-ce` and `@synapcores/sdk@^0.4.0`. The full surface — parity API (recall/capture/forget) **plus all four SynapCores-only extensions** (`recallFiltered`, `recallRelated`, `predictRelevance`, `trainRelevanceModel`) — is wired against the live SDK and exercised end-to-end (7/7 live smoke steps pass against `:28201`).
+> **0.4.0 shipping note:** the core memory ops (`memory_store` / `memory_recall` / `memory_forget`) now ride the engine-side `MEMORY_STORE` / `MEMORY_RECALL` / `MEMORY_FORGET` primitives via `@synapcores/sdk@^0.5.0`'s `client.memory` surface. The plugin's public API (tools, CLI, extensions, types) is unchanged — only the internal storage path moved.
 >
-> - **`recallRelated`** is now implemented (was signature-only in 0.1.0). On capture, the plugin inserts each Memory as a graph node carrying the embedding under the `embedding` property so the gateway's synthetic `SIMILAR_TO` edge resolves at MATCH time. `autoLinkSimilar: true` (default) enables this; turn it off if you don't need graph-backed recall.
-> - **`trainRelevanceModel`** is now implemented (was signature-only in 0.1.0). Feedback rows are staged in a SQL table (`openclaw_memory_relevance_training[_<workspace>]`) the gateway's AutoML can read, then trained as a regression model targeting the `score` column.
-> - SDK dep bumped to `@synapcores/sdk@^0.4.0` (which switched API-key auth to `Authorization: Bearer` and added `createVectorCollection` / `vectorCollection(name)`). The three v0.1.0 workarounds — auth-header shim, direct `/v1/vectors/collections` POSTs, direct `/v1/vectors/collections/{n}/vectors` POSTs — are deleted in favour of the SDK's typed helpers.
+> - **Requires SynapCores gateway `v1.8.5-ce` or newer** (the version that ships the `MEMORY_*` SQL functions).
+> - **Embedding moved server-side for the hot path.** `memory_store` / `memory_recall` no longer call OpenAI — the gateway embeds via its configured model. The OpenAI client is still used by the relevance extensions (`predictRelevance`, `trainRelevanceModel`) and the `autoLinkSimilar` graph-node embedding.
+> - **Migration from 0.3.x: the engine-managed table is `_memory_<namespace>`, a different storage backend from the v0.3.x vector collection. Existing v0.3.x memories WILL NOT appear after upgrade — re-capture them.** See "Upgrading from 0.3.x" below.
+> - **`collection` config field becomes the engine `namespace`.** It must now match `^[A-Za-z_][A-Za-z0-9_]*$`. The default `openclaw_memories` continues to work; other custom values with hyphens or other non-identifier characters need updating.
+> - **`recallFiltered` WHERE clauses run engine-side** against the `MEMORY_RECALL(?, ?, ?)` result-set. The plugin auto-rewrites the four legacy column shorthands (`category`, `importance`, `createdAt`, `text`) into the JSON-extract form so most existing call sites keep working unchanged.
+
+## Upgrading from 0.3.x
+
+`@synapcores/openclaw-memory@0.4.0` is a **hard cut**: the storage backend changes, so old memories will not migrate automatically. Steps:
+
+1. Upgrade the SynapCores gateway to `v1.8.5-ce` or newer.
+2. `npm install @synapcores/openclaw-memory@0.4.0`.
+3. If your `collection` config value contains hyphens or other non-identifier characters, rename it to match `^[A-Za-z_][A-Za-z0-9_]*$` before restarting.
+4. (Optional) export any high-value memories from the v0.3.x vector collection (the legacy `openclaw_memories` collection in your gateway) and re-store them via `memory_store` so they land in the new `_memory_<namespace>` table.
+5. (Optional) drop the old vector collection from the gateway once you're sure the export is done.
+
+If your `recallFiltered` callers use plain column names (`category`, `importance`, `createdAt`, `text`), they continue to work via auto-rewrite. Callers using the more general SQL surface should switch to the JSON-extract form (`metadata->>'…'`) directly.
 
 ## Why use this over `@openclaw/memory-lancedb`?
 
@@ -225,9 +239,9 @@ await plugin.extensions.trainRelevanceModel(feedback);
 
 Requires at least 10 samples; throws otherwise. Train periodically (cron / on-demand) — the next `predictRelevance` call will detect the model and switch out of heuristic mode.
 
-Under the hood, v0.2.0 stages feedback rows in a SQL table (`openclaw_memory_relevance_training[_<workspace>]`) on the gateway, then calls `/v1/automl/train` with `target: 'score'` and `task: 'regression'`. The table is preserved across calls so feedback accumulates between sessions; clear it manually with `DROP TABLE` (via `client.executeQuery`) if you want a clean restart.
+Under the hood, v0.4.0 stages feedback rows in a SQL table (`openclaw_memory_relevance_training[_<workspace>]`) on the gateway, then calls `/v1/automl/train` with `target: 'score'` and `task: 'regression'`. The table is preserved across calls so feedback accumulates between sessions; clear it manually with `DROP TABLE` (via `client.executeQuery`) if you want a clean restart. Memory hydration is via `MEMORY_RECALL(?, ?, ?) WHERE id = ?` against the engine's namespace; rows whose memories have been deleted are skipped.
 
-## Roadmap (0.3.0+)
+## Roadmap (0.5.0+)
 
 - **Entity extraction on capture** — parse `@mention` tokens and known-contact names out of incoming text and create `Person` / `Project` graph nodes with `MENTIONS` edges back to the memory.
 - **Tag inference** — auto-classify memories into a configurable tag vocabulary on capture (small classifier or LLM call) so `recallFiltered` queries can use tags out of the box.

package/dist/index.d.ts

@@ -2,19 +2,29 @@
  * OpenClaw Memory (SynapCores) Plugin
  *
  * Long-term memory with vector search for AI conversations.
- * Uses SynapCores AIDB for storage and OpenAI for embeddings.
+ * Uses SynapCores AIDB for storage via the engine-side
+ * `MEMORY_STORE` / `MEMORY_RECALL` / `MEMORY_FORGET` primitives and
+ * OpenAI for the relevance-extension features that still need a
+ * client-side embedding (cosine feature in `predictRelevance`,
+ * graph-node embedding when `autoLinkSimilar` is on).
+ *
  * 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`.
+ * plus four SynapCores-only extensions (SQL-filtered recall, graph-relation
+ * walks, AutoML relevance scoring, and a model-training helper) — see
+ * `recallFiltered`, `recallRelated`, `predictRelevance`, and
+ * `trainRelevanceModel`.
  *
- * This is the @synapcores/openclaw-memory drop-in alternative to
- * @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`.
+ * v0.4.0 migrates the core memory ops to `@synapcores/sdk@^0.5.0`'s
+ * `client.memory` surface. Requires SynapCores gateway v1.8.5-ce+.
  */
 import { type MemoryCategory } from "./config.js";
+/**
+ * Internal memory record shape used throughout the plugin. The legacy v0.3.x
+ * surface guaranteed `vector: number[]` on every entry because storage went
+ * through `client.vectorCollection(...)`. v0.4.0's `client.memory.recall`
+ * does not return embeddings — `vector` is filled lazily by callers that
+ * need it (currently only `predictRelevance` / `trainRelevanceModel`).
+ */
 export type MemoryEntry = {
     id: string;
     text: string;
@@ -33,9 +43,21 @@ export type MemorySearchResult = {
  * importance thresholds, category equality, etc.).
  */
 export type RecallFilteredOptions = {
-    /** SQL fragment applied as the search filter (e.g. `category = 'preference' AND importance >= 0.7`). */
+    /**
+     * SQL fragment applied as the search filter.
+     *
+     * v0.4.0 note: the WHERE clause is now evaluated against the columns
+     * returned by `MEMORY_RECALL(?, ?, ?)` — `id`, `content`, `similarity`,
+     * `metadata`, `created_at`. The legacy v0.3.x `category = 'preference'`
+     * shorthand still works for callers that wrote category/importance into
+     * the metadata blob (the plugin always does so) BUT the path is now
+     * engine-side JSON access: `metadata->>'category' = 'preference'` is the
+     * portable form. The plugin auto-rewrites a handful of the legacy
+     * shorthands (`category`, `importance`, `createdAt`, `text`) into the
+     * JSON-extract form so most existing callers keep working unchanged.
+     */
     where: string;
-    /** Natural-language query that gets embedded and used as the search vector. */
+    /** Natural-language query that gets embedded engine-side and used as the search vector. */
     semantic: string;
     /** Maximum results to return (default: 5). */
     limit?: number;
@@ -96,11 +118,12 @@ export type RelevanceFeedback = {
 /**
  * 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.
+ * Gateway v1.6.5.2+ 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 `MEMORY_STORE` (engine-generated, e.g.
+ * `mem_1kv69sxfn_5ofzwK`) 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
@@ -113,9 +136,8 @@ export declare function escapeCypherString(value: string): string;
  * them through the OpenClaw plugin registry.
  *
  * The four SynapCores-only methods use:
- *   - `vectorCollection.search({ ..., filter: { sql } })` for `recallFiltered`,
- *     forwarding the SQL `WHERE` clause to the gateway under
- *     `filter: { sql: where }`.
+ *   - `client.executeQuery(...)` against MEMORY_RECALL for `recallFiltered`,
+ *     wrapping the user's WHERE clause around the engine's recall result-set.
  *   - `client.graph.cypher(...)` for `recallRelated`, walking the synthetic
  *     `SIMILAR_TO` edges that resolve against `Memory.embedding`.
  *   - `client.automl.getModel(...).predict(...)` for `predictRelevance`, with
@@ -130,7 +152,7 @@ export interface MemorySynapCoresExtensions {
      *
      * @example
      *   await ext.recallFiltered({
-     *     where: "category = 'preference' AND importance >= 0.7 AND createdAt > 1700000000000",
+     *     where: "category = 'preference' AND importance >= 0.7",
      *     semantic: "what kind of UI does the user prefer?",
      *     limit: 5,
      *   });
@@ -140,13 +162,13 @@ export interface MemorySynapCoresExtensions {
      * Graph walk from a memory through `SIMILAR_TO` / `MENTIONS` / `RELATES_TO`
      * edges, returning the neighborhood.
      *
-     * v0.2.0 wires this against the gateway's synthetic-SIMILAR_TO Cypher
-     * syntax (`[:SIMILAR_TO > T]`) which resolves against the `embedding`
-     * property the plugin writes onto every captured Memory node. If a
-     * source memory has not been promoted to a graph node yet (e.g.
-     * `autoLinkSimilar: false`), this returns an empty array.
+     * Wires against the gateway's synthetic-SIMILAR_TO Cypher syntax
+     * (`[:SIMILAR_TO > T]`) which resolves against the `embedding` property
+     * the plugin writes onto every captured Memory node. If a source memory
+     * has not been promoted to a graph node yet (e.g. `autoLinkSimilar:
+     * false`), this returns an empty array.
      *
-     * @param memoryId - UUID of the source memory.
+     * @param memoryId - id of the source memory (engine-assigned, e.g. `mem_...`).
      * @param options - Hops, edge-kind filter, similarity threshold, limit.
      */
     recallRelated(memoryId: string, options?: RecallRelatedOptions): Promise<RelatedMemoryResult[]>;
@@ -171,12 +193,12 @@ export interface MemorySynapCoresExtensions {
     /**
      * Train (or retrain) the AutoML model used by `predictRelevance`.
      *
-     * v0.2.0 wires this against the staged-collection workflow: feedback
-     * rows are inserted into a SQL table the gateway's AutoML can read
-     * via `SELECT * FROM {table}`, then `/v1/automl/train` is invoked with
+     * Wires against the staged-collection workflow: feedback rows are
+     * inserted into a SQL table the gateway's AutoML can read via
+     * `SELECT * FROM {table}`, then `/v1/automl/train` is invoked with
      * `target: 'score'` to fit a regression model. Existing training data
-     * in the staging table is preserved across calls so feedback
-     * accumulates across sessions.
+     * in the staging table is preserved across calls so feedback accumulates
+     * across sessions.
      *
      * @param feedback - Array of `{ memoryId, queryText, score }` samples.
      *                   Requires at least {@link MIN_TRAINING_SAMPLES} samples;

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAUH,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,uFAAuF;IACvF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,+CAA+C;IAC/C,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,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;AAsfF;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAExD;AAuGD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,0BAA0B;IACzC;;;;;;;;;OASG;IACH,cAAc,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAAC;IAE9E;;;;;;;;;;;;OAYG;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;;;;;;;;;;;;;;OAcG;IACH,mBAAmB,CAAC,QAAQ,EAAE,iBAAiB,EAAE,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACrG;AAkwBD,QAAA,MAAM,WAAW;;;;;;yIAAkC,CAAC;AAEpD,eAAe,WAAW,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AASH,OAAO,EAEL,KAAK,cAAc,EAGpB,MAAM,aAAa,CAAC;AAMrB;;;;;;GAMG;AACH,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;;;;;;;;;;;;OAYG;IACH,KAAK,EAAE,MAAM,CAAC;IACd,2FAA2F;IAC3F,QAAQ,EAAE,MAAM,CAAC;IACjB,8CAA8C;IAC9C,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,oBAAoB,GAAG;IACjC,uFAAuF;IACvF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,+CAA+C;IAC/C,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,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;AAiqBF;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAExD;AAqGD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,0BAA0B;IACzC;;;;;;;;;OASG;IACH,cAAc,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAAC;IAE9E;;;;;;;;;;;;OAYG;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;;;;;;;;;;;;;;OAcG;IACH,mBAAmB,CAAC,QAAQ,EAAE,iBAAiB,EAAE,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACrG;AA4zBD,QAAA,MAAM,WAAW;;;;;;yIAAkC,CAAC;AAEpD,eAAe,WAAW,CAAC"}