@contextableai/openclaw-memory-graphiti 0.2.0 → 0.2.1

package/bin/graphiti-mem.ts

@@ -126,6 +126,8 @@ try {
 }
 
 const graphiti = new GraphitiClient(cfg.graphiti.endpoint);
+graphiti.uuidPollIntervalMs = cfg.graphiti.uuidPollIntervalMs;
+graphiti.uuidPollMaxAttempts = cfg.graphiti.uuidPollMaxAttempts;
 const spicedb = new SpiceDbClient(cfg.spicedb);
 const currentSubject = { type: cfg.subjectType, id: cfg.subjectId } as const;
 

package/cli.ts

@@ -26,7 +26,10 @@ import { searchAuthorizedMemories } from "./search.js";
 // ============================================================================
 
 function sessionGroupId(sessionId: string): string {
-  return `session-${sessionId}`;
+  // Graphiti group_ids only allow alphanumeric, dashes, underscores.
+  // OpenClaw sessionKey can contain colons (e.g. "agent:main:main") — replace invalid chars.
+  const sanitized = sessionId.replace(/[^a-zA-Z0-9_-]/g, "-");
+  return `session-${sanitized}`;
 }
 
 // ============================================================================
@@ -334,7 +337,7 @@ export function registerCommands(cmd: Command, ctx: CliContext): void {
 
       // Ensure agent is a member of the target workspace group
       if (importWorkspace) {
-        cmdbershipGroups.add(targetGroup);
+        membershipGroups.add(targetGroup);
       }
 
       // Phase 1a: Import workspace files to Graphiti
@@ -442,7 +445,7 @@ export function registerCommands(cmd: Command, ctx: CliContext): void {
                 group_id: sessionGroup,
                 source: "message",
               });
-              cmdbershipGroups.add(sessionGroup);
+              membershipGroups.add(sessionGroup);
               pendingResolutions.push({
                 resolvedUuid: result.resolvedUuid,
                 groupId: sessionGroup,

package/config.ts

@@ -7,6 +7,8 @@ export type GraphitiMemoryConfig = {
   graphiti: {
     endpoint: string;
     defaultGroupId: string;
+    uuidPollIntervalMs: number;
+    uuidPollMaxAttempts: number;
   };
   subjectType: "agent" | "person";
   subjectId: string;
@@ -19,6 +21,8 @@ export type GraphitiMemoryConfig = {
 const DEFAULT_SPICEDB_ENDPOINT = "localhost:50051";
 const DEFAULT_GRAPHITI_ENDPOINT = "http://localhost:8000";
 const DEFAULT_GROUP_ID = "main";
+const DEFAULT_UUID_POLL_INTERVAL_MS = 3000;
+const DEFAULT_UUID_POLL_MAX_ATTEMPTS = 30;
 const DEFAULT_SUBJECT_TYPE = "agent";
 const DEFAULT_MAX_CAPTURE_MESSAGES = 10;
 
@@ -72,7 +76,7 @@ export const graphitiMemoryConfigSchema = {
 
     // Graphiti config
     const graphiti = (cfg.graphiti as Record<string, unknown>) ?? {};
-    assertAllowedKeys(graphiti, ["endpoint", "defaultGroupId"], "graphiti config");
+    assertAllowedKeys(graphiti, ["endpoint", "defaultGroupId", "uuidPollIntervalMs", "uuidPollMaxAttempts"], "graphiti config");
 
     // Subject
     const subjectType = cfg.subjectType === "person" ? "person" : DEFAULT_SUBJECT_TYPE;
@@ -93,6 +97,14 @@ export const graphitiMemoryConfigSchema = {
           typeof graphiti.defaultGroupId === "string"
             ? graphiti.defaultGroupId
             : DEFAULT_GROUP_ID,
+        uuidPollIntervalMs:
+          typeof graphiti.uuidPollIntervalMs === "number" && graphiti.uuidPollIntervalMs > 0
+            ? graphiti.uuidPollIntervalMs
+            : DEFAULT_UUID_POLL_INTERVAL_MS,
+        uuidPollMaxAttempts:
+          typeof graphiti.uuidPollMaxAttempts === "number" && graphiti.uuidPollMaxAttempts > 0
+            ? Math.round(graphiti.uuidPollMaxAttempts)
+            : DEFAULT_UUID_POLL_MAX_ATTEMPTS,
       },
       subjectType,
       subjectId,

package/docker/docker-compose.yml

@@ -80,6 +80,7 @@ services:
       - "${GRAPHITI_PORT:-8000}:8000"    # MCP HTTP endpoint
     environment:
       - OPENAI_API_KEY=${OPENAI_API_KEY}
+      - EPISODE_ID_PREFIX=${EPISODE_ID_PREFIX:-epi-}
       - FALKORDB_URI=redis://host.docker.internal:${FALKORDB_PORT:-6379}
     depends_on:
       falkordb:

package/graphiti.ts

@@ -78,9 +78,9 @@ export class GraphitiClient {
   private initPromise: Promise<void> | null = null;
 
   /** Polling interval (ms) for UUID resolution after addEpisode. */
-  uuidPollIntervalMs = 2000;
+  uuidPollIntervalMs = 3000;
   /** Max polling attempts for UUID resolution (total wait = interval * attempts). */
-  uuidPollMaxAttempts = 15;
+  uuidPollMaxAttempts = 30;
 
   constructor(private readonly endpoint: string) {}
 
@@ -267,7 +267,7 @@ export class GraphitiClient {
     // Note: The Graphiti MCP server's uuid parameter is for re-processing
     // existing episodes, NOT for setting the UUID of new ones. We generate
     // a client-side tracking UUID instead (it won't match the server-side UUID).
-    const trackingUuid = randomUUID();
+    const trackingUuid = `tmp-${randomUUID()}`;
 
     // Prepend custom extraction instructions to episode_body since the MCP
     // server doesn't support custom_extraction_instructions as a parameter.
@@ -309,18 +309,22 @@ export class GraphitiClient {
   }
 
   private async resolveEpisodeUuid(name: string, groupId: string): Promise<string> {
+    const totalTimeoutSec = (this.uuidPollMaxAttempts * this.uuidPollIntervalMs) / 1000;
     for (let i = 0; i < this.uuidPollMaxAttempts; i++) {
       await new Promise((r) => setTimeout(r, this.uuidPollIntervalMs));
       try {
         const episodes = await this.getEpisodes(groupId, 50);
         const match = episodes.find((ep) => ep.name === name);
         if (match) return match.uuid;
-      } catch {
-        // Retry on transient errors
+      } catch (err) {
+        // Log transient errors to aid debugging
+        console.warn(
+          `[graphiti] UUID poll ${i + 1}/${this.uuidPollMaxAttempts} for "${name}" in "${groupId}" failed: ${err instanceof Error ? err.message : String(err)}`,
+        );
       }
     }
     throw new Error(
-      `Failed to resolve episode UUID for "${name}" in group "${groupId}" after ${(this.uuidPollMaxAttempts * this.uuidPollIntervalMs) / 1000}s`,
+      `Failed to resolve episode UUID for "${name}" in group "${groupId}" after ${totalTimeoutSec}s — episode not yet visible in get_episodes (Graphiti LLM processing may still be running)`,
     );
   }
 

package/index.ts

@@ -22,8 +22,6 @@ import { SpiceDbClient } from "./spicedb.js";
 import {
   lookupAuthorizedGroups,
   writeFragmentRelationships,
-  deleteFragmentRelationships,
-  canDeleteFragment,
   canWriteToGroup,
   ensureGroupMembership,
   type Subject,
@@ -40,8 +38,10 @@ import { registerCommands } from "./cli.js";
 // ============================================================================
 
 function sessionGroupId(sessionId: string): string {
-  // Use dash separator — Graphiti group_ids only allow alphanumeric, dashes, underscores
-  return `session-${sessionId}`;
+  // Graphiti group_ids only allow alphanumeric, dashes, underscores.
+  // OpenClaw sessionKey can contain colons (e.g. "agent:main:main") — replace invalid chars.
+  const sanitized = sessionId.replace(/[^a-zA-Z0-9_-]/g, "-");
+  return `session-${sanitized}`;
 }
 
 function isSessionGroup(groupId: string): boolean {
@@ -63,6 +63,8 @@ const memoryGraphitiPlugin = {
     const cfg = graphitiMemoryConfigSchema.parse(api.pluginConfig);
 
     const graphiti = new GraphitiClient(cfg.graphiti.endpoint);
+    graphiti.uuidPollIntervalMs = cfg.graphiti.uuidPollIntervalMs;
+    graphiti.uuidPollMaxAttempts = cfg.graphiti.uuidPollMaxAttempts;
     const spicedb = new SpiceDbClient(cfg.spicedb);
 
     const currentSubject: Subject = {
@@ -77,10 +79,6 @@ const memoryGraphitiPlugin = {
     // Reads use at_least_as_fresh(token) after own writes, minimize_latency otherwise.
     let lastWriteToken: string | undefined;
 
-    // Map tracking UUIDs to resolvedUuid promises so memory_forget can translate
-    // a tracking UUID (from memory_store) to the real server-side UUID.
-    const pendingResolutions = new Map<string, Promise<string>>();
-
     api.logger.info(
       `memory-graphiti: registered (graphiti: ${cfg.graphiti.endpoint}, spicedb: ${cfg.spicedb.endpoint})`,
     );
@@ -297,19 +295,17 @@ const memoryGraphitiPlugin = {
             custom_extraction_instructions: cfg.customInstructions,
           });
 
-          // 2. Write authorization relationships in SpiceDB (background).
-          // Graphiti processes episodes asynchronously — the real UUID isn't
-          // available immediately. resolvedUuid polls in the background and
-          // writes SpiceDB relationships once the real UUID is known, so the
-          // tool response isn't blocked.
+          // 2. Write authorization relationships in SpiceDB (background)
           const involvedSubjects: Subject[] = involves.map((id) => ({
             type: "person" as const,
             id,
           }));
 
-          // Chain UUID resolution → SpiceDB write, and store the promise so
-          // memory_forget can await both before checking permissions.
-          const deferredWrite = result.resolvedUuid
+          // Chain UUID resolution → SpiceDB write in the background.
+          // Graphiti processes episodes asynchronously, so the real UUID
+          // isn't available immediately. Once resolved, write SpiceDB
+          // relationships so authorization checks work for this fragment.
+          result.resolvedUuid
             .then(async (realUuid) => {
               const writeToken = await writeFragmentRelationships(spicedb, {
                 fragmentId: realUuid,
@@ -319,15 +315,13 @@ const memoryGraphitiPlugin = {
               });
               if (writeToken) lastWriteToken = writeToken;
               return realUuid;
+            })
+            .catch((err) => {
+              api.logger.warn(
+                `memory-graphiti: deferred SpiceDB write failed for memory_store: ${err}`,
+              );
             });
 
-          pendingResolutions.set(result.episode_uuid, deferredWrite);
-          deferredWrite.catch((err) => {
-            api.logger.warn(
-              `memory-graphiti: deferred SpiceDB write failed for memory_store: ${err}`,
-            );
-          });
-
           return {
             content: [
               {
@@ -353,98 +347,80 @@ const memoryGraphitiPlugin = {
         name: "memory_forget",
         label: "Memory Forget",
         description:
-          "Delete a memory episode or fact. Provide either episode_id or fact_id (not both). Requires delete/write permission.",
+          "Delete a fact from the knowledge graph by ID. Use the type-prefixed IDs from memory_recall (e.g. 'fact:UUID'). Entities cannot be deleted directly — delete the facts connected to them instead.",
         parameters: Type.Object({
-          episode_id: Type.Optional(Type.String({ description: "Episode UUID to delete" })),
-          fact_id: Type.Optional(Type.String({ description: "Fact (entity edge) UUID to delete" })),
+          id: Type.String({ description: "Fact ID to delete (e.g. 'fact:da8650cb-...')" }),
         }),
         async execute(_toolCallId, params) {
-          const { episode_id, fact_id } = params as { episode_id?: string; fact_id?: string };
+          const { id } = params as { id: string };
+
+          // Parse type prefix from ID (e.g. "fact:da8650cb-..." → type="fact", uuid="da8650cb-...")
+          const colonIdx = id.indexOf(":");
+          let idType: "fact" | "entity" | "episode";
+          let uuid: string;
+
+          if (colonIdx > 0 && colonIdx < 10) {
+            const prefix = id.slice(0, colonIdx);
+            uuid = id.slice(colonIdx + 1);
+            if (prefix === "fact") {
+              idType = "fact";
+            } else if (prefix === "entity") {
+              idType = "entity";
+            } else {
+              // Unknown prefix — treat as bare episode UUID
+              idType = "episode";
+              uuid = id;
+            }
+          } else {
+            idType = "episode";
+            uuid = id;
+          }
 
-          if (!episode_id && !fact_id) {
+          // --- Entity: not deletable via MCP server ---
+          if (idType === "entity") {
             return {
-              content: [{ type: "text", text: "Either episode_id or fact_id must be provided." }],
-              details: { action: "error" },
+              content: [{ type: "text", text: `Entities cannot be deleted directly. To remove information about an entity, delete the specific facts (edges) connected to it.` }],
+              details: { action: "error", id },
             };
           }
 
           // --- Fact deletion ---
-          if (fact_id) {
-            // 1. Fetch fact to get group_id for authorization
+          if (idType === "fact") {
             let fact: Awaited<ReturnType<typeof graphiti.getEntityEdge>>;
             try {
-              fact = await graphiti.getEntityEdge(fact_id);
+              fact = await graphiti.getEntityEdge(uuid);
             } catch {
               return {
-                content: [{ type: "text", text: `Fact ${fact_id} not found.` }],
-                details: { action: "error", factId: fact_id },
+                content: [{ type: "text", text: `Fact ${uuid} not found.` }],
+                details: { action: "not_found", id },
               };
             }
 
-            // 2. Check write permission on the fact's group
-            const allowed = await canWriteToGroup(spicedb, currentSubject, fact.group_id, lastWriteToken);
+            // Graphiti allows empty-string group_ids (its default for some backends),
+            // but SpiceDB ObjectIds require at least one character. Map empty to the
+            // configured default so the permission check doesn't fail with INVALID_ARGUMENT.
+            const effectiveGroupId = fact.group_id || cfg.graphiti.defaultGroupId;
+            const allowed = await canWriteToGroup(spicedb, currentSubject, effectiveGroupId, lastWriteToken);
             if (!allowed) {
               return {
-                content: [{ type: "text", text: `Permission denied: cannot delete fact ${fact_id}` }],
-                details: { action: "denied", factId: fact_id },
+                content: [{ type: "text", text: `Permission denied: cannot delete fact in group "${effectiveGroupId}"` }],
+                details: { action: "denied", id },
               };
             }
 
-            // 3. Delete fact from Graphiti
-            await graphiti.deleteEntityEdge(fact_id);
-
-            return {
-              content: [{ type: "text", text: `Fact ${fact_id} forgotten.` }],
-              details: { action: "deleted", factId: fact_id },
-            };
-          }
-
-          // --- Episode deletion (existing flow) ---
-
-          // Resolve tracking UUID → real server-side UUID if this came
-          // from a recent memory_store call. Awaits the background
-          // resolution so permission checks use the correct UUID.
-          let effectiveId = episode_id!;
-          const pending = pendingResolutions.get(episode_id!);
-          if (pending) {
-            try {
-              effectiveId = await pending;
-            } catch {
-              // Resolution failed — try with original UUID
-            }
-            pendingResolutions.delete(episode_id!);
-          }
+            await graphiti.deleteEntityEdge(uuid);
 
-          // 1. Check delete permission
-          const allowed = await canDeleteFragment(spicedb, currentSubject, effectiveId, lastWriteToken);
-          if (!allowed) {
             return {
-              content: [
-                {
-                  type: "text",
-                  text: `Permission denied: cannot delete episode ${episode_id}`,
-                },
-              ],
-              details: { action: "denied", episodeId: episode_id },
+              content: [{ type: "text", text: `Fact forgotten.` }],
+              details: { action: "deleted", id, type: "fact" },
             };
           }
 
-          // 2. Delete from Graphiti
-          await graphiti.deleteEpisode(effectiveId);
-
-          // 3. Clean up SpiceDB relationships (best-effort)
-          try {
-            const deleteToken = await deleteFragmentRelationships(spicedb, effectiveId);
-            if (deleteToken) lastWriteToken = deleteToken;
-          } catch {
-            api.logger.warn(
-              `memory-graphiti: failed to clean up SpiceDB relationships for ${episode_id}`,
-            );
-          }
-
+          // --- Bare UUID / episode: not supported via agent tool ---
+          // Episode deletion is an admin operation available via CLI (graphiti-mem cleanup).
           return {
-            content: [{ type: "text", text: `Memory ${episode_id} forgotten.` }],
-            details: { action: "deleted", episodeId: episode_id },
+            content: [{ type: "text", text: `Unrecognized ID format "${id}". Use IDs from memory_recall (e.g. 'fact:da8650cb-...'). Episode deletion is available via the CLI.` }],
+            details: { action: "error", id },
           };
         },
       },
@@ -729,7 +705,7 @@ const memoryGraphitiPlugin = {
           spicedbOk = true;
 
           // Auto-write schema if SpiceDB has no schema yet
-          if (!existing || !existing.includes("memory_group")) {
+          if (!existing || !existing.includes("memory_fragment")) {
             api.logger.info("memory-graphiti: writing SpiceDB schema (first run)");
             const schemaPath = join(dirname(fileURLToPath(import.meta.url)), "schema.zed");
             const schema = readFileSync(schemaPath, "utf-8");

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.2.0",
+  "version": "0.2.1",
   "description": "OpenClaw two-layer memory plugin: SpiceDB authorization + Graphiti knowledge graph",
   "type": "module",
   "license": "MIT",

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

@@ -138,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",
@@ -164,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");
 }
 
 /**
@@ -185,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).
  */