@contextableai/openclaw-memory-graphiti 0.1.2 → 0.2.1

package/openclaw.plugin.json

@@ -27,6 +27,18 @@
       "placeholder": "main",
       "help": "Default Graphiti group_id for memory isolation"
     },
+    "graphiti.uuidPollIntervalMs": {
+      "label": "UUID Poll Interval (ms)",
+      "placeholder": "3000",
+      "help": "Milliseconds between polling attempts when resolving episode UUIDs after memory_store (default: 3000)",
+      "advanced": true
+    },
+    "graphiti.uuidPollMaxAttempts": {
+      "label": "UUID Poll Max Attempts",
+      "placeholder": "30",
+      "help": "Maximum polling attempts for episode UUID resolution; total timeout = interval × attempts (default: 30 = 90s)",
+      "advanced": true
+    },
     "subjectType": {
       "label": "Subject Type",
       "placeholder": "agent",
@@ -76,7 +88,9 @@
         "additionalProperties": false,
         "properties": {
           "endpoint": { "type": "string" },
-          "defaultGroupId": { "type": "string" }
+          "defaultGroupId": { "type": "string" },
+          "uuidPollIntervalMs": { "type": "integer", "minimum": 500, "maximum": 30000 },
+          "uuidPollMaxAttempts": { "type": "integer", "minimum": 1, "maximum": 200 }
         }
       },
       "subjectType": { "type": "string", "enum": ["agent", "person"] },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contextableai/openclaw-memory-graphiti",
-  "version": "0.1.2",
+  "version": "0.2.1",
   "description": "OpenClaw two-layer memory plugin: SpiceDB authorization + Graphiti knowledge graph",
   "type": "module",
   "license": "MIT",
@@ -18,6 +18,7 @@
   ],
   "files": [
     "index.ts",
+    "cli.ts",
     "config.ts",
     "authorization.ts",
     "graphiti.ts",
@@ -26,27 +27,31 @@
     "openclaw.plugin.json",
     "schema.zed",
     "docker/",
-    "scripts/"
+    "scripts/",
+    "bin/"
   ],
   "scripts": {
+    "cli": "tsx bin/graphiti-mem.ts",
+    "typecheck": "tsc --noEmit 2>&1 | grep -v '../openclaw/' | grep -c 'error TS' | xargs -I{} test {} -eq 0",
     "test": "vitest run",
     "test:watch": "vitest",
     "test:e2e": "OPENCLAW_LIVE_TEST=1 vitest run --config vitest.e2e.config.ts"
   },
   "dependencies": {
     "@authzed/authzed-node": "^1.2.0",
-    "@sinclair/typebox": "0.34.48"
+    "@sinclair/typebox": "0.34.48",
+    "commander": "^13.1.0"
   },
   "devDependencies": {
+    "typescript": "^5.9.3",
     "vitest": "^4.0.18"
   },
   "publishConfig": {
     "access": "public"
   },
   "openclaw": {
-    "extensions": [
-      "./index.ts"
-    ],
+    "_extensions_note": "Intentionally empty — explicit entries cause idHint to derive from the npm package name rather than the directory name, producing a mismatch with the manifest id. Previously: [\"./index.ts\"]",
+    "extensions": [],
     "install": {
       "npmSpec": "@contextableai/openclaw-memory-graphiti",
       "localPath": "extensions/memory-graphiti",

package/scripts/dev-start.sh

@@ -13,6 +13,7 @@
 #   SPICEDB_DB_URI        Postgres connection URI (when SPICEDB_DATASTORE=postgres)
 #   FALKORDB_PORT         Redis port (default: 6379)
 #   GRAPHITI_PORT         HTTP port (default: 8000)
+#   EPISODE_ID_PREFIX     Prefix for Graphiti episode UUIDs (default: epi-)
 # -------------------------------------------------------------------
 set -euo pipefail
 
@@ -63,6 +64,8 @@ if is_running "$DEV_DIR/pids/falkordb.pid"; then
   echo "==> FalkorDB already running (pid $(cat "$DEV_DIR/pids/falkordb.pid"))"
 else
   echo "==> Starting FalkorDB on port $FALKORDB_PORT..."
+  # Redis 8.x requires a valid locale; default to C.utf8 if LANG is unset
+  export LC_ALL="${LC_ALL:-C.utf8}"
   redis-server \
     --loadmodule "$DEV_DIR/lib/falkordb.so" \
     --port "$FALKORDB_PORT" \
@@ -190,6 +193,7 @@ else
   # Set environment for Graphiti
   export OPENAI_API_KEY="${OPENAI_API_KEY:-}"
   export FALKORDB_URI="redis://localhost:$FALKORDB_PORT"
+  export EPISODE_ID_PREFIX="${EPISODE_ID_PREFIX:-epi-}"
 
   cd "$GRAPHITI_DIR"
   uv run main.py \

package/search.ts

@@ -27,6 +27,8 @@ export type SearchOptions = {
   limit?: number;
   searchNodes?: boolean;
   searchFacts?: boolean;
+  entityTypes?: string[];
+  centerNodeUuid?: string;
 };
 
 // ============================================================================
@@ -41,7 +43,15 @@ export async function searchAuthorizedMemories(
   graphiti: GraphitiClient,
   options: SearchOptions,
 ): Promise<SearchResult[]> {
-  const { query, groupIds, limit = 10, searchNodes = true, searchFacts = true } = options;
+  const {
+    query,
+    groupIds,
+    limit = 10,
+    searchNodes = true,
+    searchFacts = true,
+    entityTypes,
+    centerNodeUuid,
+  } = options;
 
   if (groupIds.length === 0) {
     return [];
@@ -52,10 +62,10 @@ export async function searchAuthorizedMemories(
 
   for (const groupId of groupIds) {
     if (searchNodes) {
-      promises.push(searchNodesForGroup(graphiti, query, groupId, limit));
+      promises.push(searchNodesForGroup(graphiti, query, groupId, limit, entityTypes));
     }
     if (searchFacts) {
-      promises.push(searchFactsForGroup(graphiti, query, groupId, limit));
+      promises.push(searchFactsForGroup(graphiti, query, groupId, limit, centerNodeUuid));
     }
   }
 
@@ -99,8 +109,9 @@ async function searchNodesForGroup(
   query: string,
   groupId: string,
   limit: number,
+  entityTypes?: string[],
 ): Promise<SearchResult[]> {
-  const nodes = await graphiti.searchNodes({ query, group_id: groupId, limit });
+  const nodes = await graphiti.searchNodes({ query, group_id: groupId, limit, entity_types: entityTypes });
   return nodes.map(nodeToResult);
 }
 
@@ -109,8 +120,9 @@ async function searchFactsForGroup(
   query: string,
   groupId: string,
   limit: number,
+  centerNodeUuid?: string,
 ): Promise<SearchResult[]> {
-  const facts = await graphiti.searchFacts({ query, group_id: groupId, limit });
+  const facts = await graphiti.searchFacts({ query, group_id: groupId, limit, center_node_uuid: centerNodeUuid });
   return facts.map(factToResult);
 }
 
@@ -126,9 +138,10 @@ function nodeToResult(node: GraphitiNode): SearchResult {
 }
 
 function factToResult(fact: GraphitiFact): SearchResult {
-  // Use node names if available, fall back to relationship name or UUIDs
-  const source = fact.source_node_name ?? fact.source_node_uuid ?? "?";
-  const target = fact.target_node_name ?? fact.target_node_uuid ?? "?";
+  // Use node names only — never expose raw node UUIDs in the formatted output.
+  // Bare UUIDs in context strings cause LLMs to confuse node IDs with fact/episode IDs.
+  const source = fact.source_node_name ?? "?";
+  const target = fact.target_node_name ?? "?";
   const context = fact.name ? `${source} -[${fact.name}]→ ${target}` : `${source} → ${target}`;
   return {
     type: "fact",
@@ -152,12 +165,7 @@ export function formatResultsForContext(results: SearchResult[]): string {
     return "";
   }
 
-  return results
-    .map((r, i) => {
-      const typeLabel = r.type === "node" ? "entity" : "fact";
-      return `${i + 1}. [${typeLabel}] ${r.summary} (${r.context})`;
-    })
-    .join("\n");
+  return results.map((r, i) => formatResultLine(r, i + 1)).join("\n");
 }
 
 /**
@@ -173,22 +181,30 @@ export function formatDualResults(
 
   if (longTermResults.length > 0) {
     for (const r of longTermResults) {
-      const typeLabel = r.type === "node" ? "entity" : "fact";
-      parts.push(`${idx++}. [${typeLabel}] ${r.summary} (${r.context})`);
+      parts.push(formatResultLine(r, idx++));
     }
   }
 
   if (sessionResults.length > 0) {
     parts.push("Session memories:");
     for (const r of sessionResults) {
-      const typeLabel = r.type === "node" ? "entity" : "fact";
-      parts.push(`${idx++}. [${typeLabel}] ${r.summary} (${r.context})`);
+      parts.push(formatResultLine(r, idx++));
     }
   }
 
   return parts.join("\n");
 }
 
+/**
+ * Format a single search result line with type-prefixed UUID.
+ * e.g. "[fact:da8650cb-...] Eric's birthday is Dec 17th (Eric -[HAS_BIRTHDAY]→ Dec 17th)"
+ * The type prefix tells the LLM which deletion method to use.
+ */
+function formatResultLine(r: SearchResult, idx: number): string {
+  const typeLabel = r.type === "node" ? "entity" : "fact";
+  return `${idx}. [${typeLabel}:${r.uuid}] ${r.summary} (${r.context})`;
+}
+
 /**
  * Deduplicate session results against long-term results (by UUID).
  */

package/spicedb.ts

@@ -2,7 +2,8 @@
  * SpiceDB Client Wrapper
  *
  * Wraps @authzed/authzed-node for authorization operations:
- * WriteSchema, WriteRelationships, LookupResources, CheckPermission.
+ * WriteSchema, WriteRelationships, DeleteRelationships, BulkImportRelationships,
+ * LookupResources, CheckPermission.
  */
 
 import { v1 } from "@authzed/authzed-node";
@@ -25,6 +26,11 @@ export type RelationshipTuple = {
   subjectId: string;
 };
 
+export type ConsistencyMode =
+  | { mode: "full" }
+  | { mode: "at_least_as_fresh"; token: string }
+  | { mode: "minimize_latency" };
+
 // ============================================================================
 // Client
 // ============================================================================
@@ -65,7 +71,7 @@ export class SpiceDbClient {
   // Relationships
   // --------------------------------------------------------------------------
 
-  async writeRelationships(tuples: RelationshipTuple[]): Promise<void> {
+  async writeRelationships(tuples: RelationshipTuple[]): Promise<string | undefined> {
     const updates = tuples.map((t) =>
       v1.RelationshipUpdate.create({
         operation: v1.RelationshipUpdate_Operation.TOUCH,
@@ -86,7 +92,8 @@ export class SpiceDbClient {
     );
 
     const request = v1.WriteRelationshipsRequest.create({ updates });
-    await this.promises.writeRelationships(request);
+    const response = await this.promises.writeRelationships(request);
+    return response.writtenAt?.token;
   }
 
   async deleteRelationships(tuples: RelationshipTuple[]): Promise<void> {
@@ -113,16 +120,193 @@ export class SpiceDbClient {
     await this.promises.writeRelationships(request);
   }
 
+  async deleteRelationshipsByFilter(params: {
+    resourceType: string;
+    resourceId: string;
+    relation?: string;
+  }): Promise<string | undefined> {
+    const request = v1.DeleteRelationshipsRequest.create({
+      relationshipFilter: v1.RelationshipFilter.create({
+        resourceType: params.resourceType,
+        optionalResourceId: params.resourceId,
+        ...(params.relation ? { optionalRelation: params.relation } : {}),
+      }),
+    });
+
+    const response = await this.promises.deleteRelationships(request);
+    return response.deletedAt?.token;
+  }
+
+  // --------------------------------------------------------------------------
+  // Bulk Import
+  // --------------------------------------------------------------------------
+
+  private toRelationship(t: RelationshipTuple) {
+    return v1.Relationship.create({
+      resource: v1.ObjectReference.create({
+        objectType: t.resourceType,
+        objectId: t.resourceId,
+      }),
+      relation: t.relation,
+      subject: v1.SubjectReference.create({
+        object: v1.ObjectReference.create({
+          objectType: t.subjectType,
+          objectId: t.subjectId,
+        }),
+      }),
+    });
+  }
+
+  /**
+   * Bulk import relationships using the streaming ImportBulkRelationships RPC.
+   * More efficient than individual writeRelationships calls for large batches.
+   * Falls back to batched writeRelationships if the streaming RPC is unavailable.
+   */
+  async bulkImportRelationships(
+    tuples: RelationshipTuple[],
+    batchSize = 1000,
+  ): Promise<number> {
+    if (tuples.length === 0) return 0;
+
+    // Try streaming bulk import first
+    if (typeof this.promises.bulkImportRelationships === "function") {
+      return this.bulkImportViaStream(tuples, batchSize);
+    }
+
+    // Fallback: batched writeRelationships
+    return this.bulkImportViaWrite(tuples, batchSize);
+  }
+
+  private bulkImportViaStream(
+    tuples: RelationshipTuple[],
+    batchSize: number,
+  ): Promise<number> {
+    return new Promise((resolve, reject) => {
+      const stream = this.promises.bulkImportRelationships(
+        (err: Error | null, response?: { numLoaded?: string }) => {
+          if (err) reject(err);
+          else resolve(Number(response?.numLoaded ?? tuples.length));
+        },
+      );
+
+      stream.on("error", (err: Error) => {
+        reject(err);
+      });
+
+      for (let i = 0; i < tuples.length; i += batchSize) {
+        const chunk = tuples.slice(i, i + batchSize);
+        stream.write(
+          v1.BulkImportRelationshipsRequest.create({
+            relationships: chunk.map((t) => this.toRelationship(t)),
+          }),
+        );
+      }
+
+      stream.end();
+    });
+  }
+
+  private async bulkImportViaWrite(
+    tuples: RelationshipTuple[],
+    batchSize: number,
+  ): Promise<number> {
+    let total = 0;
+    for (let i = 0; i < tuples.length; i += batchSize) {
+      const chunk = tuples.slice(i, i + batchSize);
+      await this.writeRelationships(chunk);
+      total += chunk.length;
+    }
+    return total;
+  }
+
+  // --------------------------------------------------------------------------
+  // Read Relationships
+  // --------------------------------------------------------------------------
+
+  /**
+   * Read relationships matching a filter. Returns all tuples that match the
+   * specified resource type, optional resource ID, optional relation, and
+   * optional subject filter. Used by the cleanup command to find which
+   * Graphiti episodes have SpiceDB authorization relationships.
+   */
+  async readRelationships(params: {
+    resourceType: string;
+    resourceId?: string;
+    relation?: string;
+    subjectType?: string;
+    subjectId?: string;
+    consistency?: ConsistencyMode;
+  }): Promise<RelationshipTuple[]> {
+    const filterFields: Record<string, unknown> = {
+      resourceType: params.resourceType,
+    };
+    if (params.resourceId) {
+      filterFields.optionalResourceId = params.resourceId;
+    }
+    if (params.relation) {
+      filterFields.optionalRelation = params.relation;
+    }
+    if (params.subjectType) {
+      const subjectFilter: Record<string, unknown> = {
+        subjectType: params.subjectType,
+      };
+      if (params.subjectId) {
+        subjectFilter.optionalSubjectId = params.subjectId;
+      }
+      filterFields.optionalSubjectFilter = v1.SubjectFilter.create(subjectFilter);
+    }
+
+    const request = v1.ReadRelationshipsRequest.create({
+      relationshipFilter: v1.RelationshipFilter.create(filterFields),
+      consistency: this.buildConsistency(params.consistency),
+    });
+
+    const results = await this.promises.readRelationships(request);
+    const tuples: RelationshipTuple[] = [];
+    for (const r of results) {
+      const rel = r.relationship;
+      if (!rel?.resource || !rel.subject?.object) continue;
+      tuples.push({
+        resourceType: rel.resource.objectType,
+        resourceId: rel.resource.objectId,
+        relation: rel.relation,
+        subjectType: rel.subject.object.objectType,
+        subjectId: rel.subject.object.objectId,
+      });
+    }
+    return tuples;
+  }
+
   // --------------------------------------------------------------------------
   // Permissions
   // --------------------------------------------------------------------------
 
+  private buildConsistency(mode?: ConsistencyMode) {
+    if (!mode || mode.mode === "minimize_latency") {
+      return v1.Consistency.create({
+        requirement: { oneofKind: "minimizeLatency", minimizeLatency: true },
+      });
+    }
+    if (mode.mode === "at_least_as_fresh") {
+      return v1.Consistency.create({
+        requirement: {
+          oneofKind: "atLeastAsFresh",
+          atLeastAsFresh: v1.ZedToken.create({ token: mode.token }),
+        },
+      });
+    }
+    return v1.Consistency.create({
+      requirement: { oneofKind: "fullyConsistent", fullyConsistent: true },
+    });
+  }
+
   async checkPermission(params: {
     resourceType: string;
     resourceId: string;
     permission: string;
     subjectType: string;
     subjectId: string;
+    consistency?: ConsistencyMode;
   }): Promise<boolean> {
     const request = v1.CheckPermissionRequest.create({
       resource: v1.ObjectReference.create({
@@ -136,9 +320,7 @@ export class SpiceDbClient {
           objectId: params.subjectId,
         }),
       }),
-      consistency: v1.Consistency.create({
-        requirement: { oneofKind: "fullyConsistent", fullyConsistent: true },
-      }),
+      consistency: this.buildConsistency(params.consistency),
     });
 
     const response = await this.promises.checkPermission(request);
@@ -153,6 +335,7 @@ export class SpiceDbClient {
     permission: string;
     subjectType: string;
     subjectId: string;
+    consistency?: ConsistencyMode;
   }): Promise<string[]> {
     const request = v1.LookupResourcesRequest.create({
       resourceObjectType: params.resourceType,
@@ -163,9 +346,7 @@ export class SpiceDbClient {
           objectId: params.subjectId,
         }),
       }),
-      consistency: v1.Consistency.create({
-        requirement: { oneofKind: "fullyConsistent", fullyConsistent: true },
-      }),
+      consistency: this.buildConsistency(params.consistency),
     });
 
     const results = await this.promises.lookupResources(request);