@contextableai/openclaw-memory-graphiti 0.1.2 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contextableai/openclaw-memory-graphiti",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "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/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);
 }
 

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);