@contextableai/openclaw-memory-graphiti 0.1.2 → 0.2.1

package/index.ts

@@ -13,9 +13,7 @@
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
 import { Type } from "@sinclair/typebox";
 import { readFileSync } from "node:fs";
-import { readdir, readFile, stat } from "node:fs/promises";
-import { join, dirname, basename, resolve } from "node:path";
-import { homedir } from "node:os";
+import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 
 import { graphitiMemoryConfigSchema } from "./config.js";
@@ -24,8 +22,6 @@ import { SpiceDbClient } from "./spicedb.js";
 import {
   lookupAuthorizedGroups,
   writeFragmentRelationships,
-  deleteFragmentRelationships,
-  canDeleteFragment,
   canWriteToGroup,
   ensureGroupMembership,
   type Subject,
@@ -35,14 +31,17 @@ import {
   formatDualResults,
   deduplicateSessionResults,
 } from "./search.js";
+import { registerCommands } from "./cli.js";
 
 // ============================================================================
 // Session helpers
 // ============================================================================
 
 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 {
@@ -64,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 = {
@@ -74,6 +75,10 @@ const memoryGraphitiPlugin = {
     // Track current session ID — updated from hook event context
     let currentSessionId: string | undefined;
 
+    // Track most recent ZedToken from SpiceDB writes for causal consistency.
+    // Reads use at_least_as_fresh(token) after own writes, minimize_latency otherwise.
+    let lastWriteToken: string | undefined;
+
     api.logger.info(
       `memory-graphiti: registered (graphiti: ${cfg.graphiti.endpoint}, spicedb: ${cfg.spicedb.endpoint})`,
     );
@@ -97,16 +102,28 @@ const memoryGraphitiPlugin = {
               { description: "Memory scope: 'session' (current session only), 'long-term' (persistent), or 'all' (both). Default: 'all'" },
             ),
           ),
+          entity_types: Type.Optional(
+            Type.Array(Type.String(), {
+              description: "Filter by entity type (e.g., 'Preference', 'Organization', 'Procedure')",
+            }),
+          ),
+          center_node_uuid: Type.Optional(
+            Type.String({
+              description: "UUID of an entity node to center the fact search around",
+            }),
+          ),
         }),
         async execute(_toolCallId, params) {
-          const { query, limit = 10, scope = "all" } = params as {
+          const { query, limit = 10, scope = "all", entity_types, center_node_uuid } = params as {
             query: string;
             limit?: number;
             scope?: "session" | "long-term" | "all";
+            entity_types?: string[];
+            center_node_uuid?: string;
           };
 
           // 1. Get authorized groups for current subject
-          const authorizedGroups = await lookupAuthorizedGroups(spicedb, currentSubject);
+          const authorizedGroups = await lookupAuthorizedGroups(spicedb, currentSubject, lastWriteToken);
 
           if (authorizedGroups.length === 0) {
             return {
@@ -145,12 +162,13 @@ const memoryGraphitiPlugin = {
           }
 
           // 3. Parallel search across groups
+          const searchOpts = { entityTypes: entity_types, centerNodeUuid: center_node_uuid };
           const [longTermResults, rawSessionResults] = await Promise.all([
             longTermGroups.length > 0
-              ? searchAuthorizedMemories(graphiti, { query, groupIds: longTermGroups, limit })
+              ? searchAuthorizedMemories(graphiti, { query, groupIds: longTermGroups, limit, ...searchOpts })
               : Promise.resolve([]),
             sessionGroups.length > 0
-              ? searchAuthorizedMemories(graphiti, { query, groupIds: sessionGroups, limit })
+              ? searchAuthorizedMemories(graphiti, { query, groupIds: sessionGroups, limit, ...searchOpts })
               : Promise.resolve([]),
           ]);
 
@@ -247,13 +265,14 @@ const memoryGraphitiPlugin = {
 
           if (isOwnSession) {
             try {
-              await ensureGroupMembership(spicedb, targetGroupId, currentSubject);
+              const token = await ensureGroupMembership(spicedb, targetGroupId, currentSubject);
+              if (token) lastWriteToken = token;
             } catch {
               api.logger.warn(`memory-graphiti: failed to ensure membership in ${targetGroupId}`);
             }
           } else {
             // All other groups (non-session AND foreign session) require write permission
-            const allowed = await canWriteToGroup(spicedb, currentSubject, targetGroupId);
+            const allowed = await canWriteToGroup(spicedb, currentSubject, targetGroupId, lastWriteToken);
             if (!allowed) {
               return {
                 content: [
@@ -276,20 +295,32 @@ const memoryGraphitiPlugin = {
             custom_extraction_instructions: cfg.customInstructions,
           });
 
-          const fragmentId = result.episode_uuid;
-
-          // 2. Write authorization relationships in SpiceDB
+          // 2. Write authorization relationships in SpiceDB (background)
           const involvedSubjects: Subject[] = involves.map((id) => ({
             type: "person" as const,
             id,
           }));
 
-          await writeFragmentRelationships(spicedb, {
-            fragmentId,
-            groupId: targetGroupId,
-            sharedBy: currentSubject,
-            involves: involvedSubjects,
-          });
+          // 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,
+                groupId: targetGroupId,
+                sharedBy: currentSubject,
+                involves: involvedSubjects,
+              });
+              if (writeToken) lastWriteToken = writeToken;
+              return realUuid;
+            })
+            .catch((err) => {
+              api.logger.warn(
+                `memory-graphiti: deferred SpiceDB write failed for memory_store: ${err}`,
+              );
+            });
 
           return {
             content: [
@@ -300,7 +331,7 @@ const memoryGraphitiPlugin = {
             ],
             details: {
               action: "created",
-              episodeId: fragmentId,
+              episodeId: result.episode_uuid,
               groupId: targetGroupId,
               longTerm,
               involves,
@@ -315,46 +346,81 @@ const memoryGraphitiPlugin = {
       {
         name: "memory_forget",
         label: "Memory Forget",
-        description: "Delete a memory episode. Requires delete permission.",
+        description:
+          "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.String({ description: "Episode UUID to delete" }),
+          id: Type.String({ description: "Fact ID to delete (e.g. 'fact:da8650cb-...')" }),
         }),
         async execute(_toolCallId, params) {
-          const { episode_id } = params as { episode_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;
+          }
 
-          // 1. Check delete permission
-          const allowed = await canDeleteFragment(spicedb, currentSubject, episode_id);
-          if (!allowed) {
+          // --- Entity: not deletable via MCP server ---
+          if (idType === "entity") {
             return {
-              content: [
-                {
-                  type: "text",
-                  text: `Permission denied: cannot delete episode ${episode_id}`,
-                },
-              ],
-              details: { action: "denied", episodeId: episode_id },
+              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 },
             };
           }
 
-          // 2. Delete from Graphiti
-          await graphiti.deleteEpisode(episode_id);
+          // --- Fact deletion ---
+          if (idType === "fact") {
+            let fact: Awaited<ReturnType<typeof graphiti.getEntityEdge>>;
+            try {
+              fact = await graphiti.getEntityEdge(uuid);
+            } catch {
+              return {
+                content: [{ type: "text", text: `Fact ${uuid} not found.` }],
+                details: { action: "not_found", id },
+              };
+            }
 
-          // 3. Clean up SpiceDB relationships (best-effort)
-          try {
-            await deleteFragmentRelationships(spicedb, episode_id, {
-              fragmentId: episode_id,
-              groupId: cfg.graphiti.defaultGroupId,
-              sharedBy: currentSubject,
-            });
-          } catch {
-            api.logger.warn(
-              `memory-graphiti: failed to clean up SpiceDB relationships for ${episode_id}`,
-            );
+            // 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 in group "${effectiveGroupId}"` }],
+                details: { action: "denied", id },
+              };
+            }
+
+            await graphiti.deleteEntityEdge(uuid);
+
+            return {
+              content: [{ type: "text", text: `Fact forgotten.` }],
+              details: { action: "deleted", id, type: "fact" },
+            };
           }
 
+          // --- 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 },
           };
         },
       },
@@ -410,298 +476,13 @@ const memoryGraphitiPlugin = {
         const mem = program
           .command("graphiti-mem")
           .description("Graphiti + SpiceDB memory plugin commands");
-
-        mem
-          .command("search")
-          .description("Search memories with authorization")
-          .argument("<query>", "Search query")
-          .option("--limit <n>", "Max results", "10")
-          .option("--scope <scope>", "Memory scope: session, long-term, all", "all")
-          .action(async (query: string, opts: { limit: string; scope: string }) => {
-            const authorizedGroups = await lookupAuthorizedGroups(spicedb, currentSubject);
-            if (authorizedGroups.length === 0) {
-              console.log("No accessible memory groups.");
-              return;
-            }
-
-            console.log(`Searching ${authorizedGroups.length} authorized groups...`);
-            const results = await searchAuthorizedMemories(graphiti, {
-              query,
-              groupIds: authorizedGroups,
-              limit: parseInt(opts.limit),
-            });
-
-            if (results.length === 0) {
-              console.log("No results found.");
-              return;
-            }
-
-            console.log(JSON.stringify(results, null, 2));
-          });
-
-        mem
-          .command("episodes")
-          .description("List recent episodes")
-          .option("--last <n>", "Number of episodes", "10")
-          .option("--group <id>", "Group ID", cfg.graphiti.defaultGroupId)
-          .action(async (opts: { last: string; group: string }) => {
-            const episodes = await graphiti.getEpisodes(opts.group, parseInt(opts.last));
-            console.log(JSON.stringify(episodes, null, 2));
-          });
-
-        mem
-          .command("status")
-          .description("Check SpiceDB + Graphiti health")
-          .action(async () => {
-            const graphitiOk = await graphiti.healthCheck();
-            let spicedbOk = false;
-            try {
-              await spicedb.readSchema();
-              spicedbOk = true;
-            } catch {
-              // unreachable
-            }
-
-            console.log(`Graphiti MCP: ${graphitiOk ? "OK" : "UNREACHABLE"} (${cfg.graphiti.endpoint})`);
-            console.log(`SpiceDB:      ${spicedbOk ? "OK" : "UNREACHABLE"} (${cfg.spicedb.endpoint})`);
-          });
-
-        mem
-          .command("schema-write")
-          .description("Write/update SpiceDB authorization schema")
-          .action(async () => {
-            const schemaPath = join(dirname(fileURLToPath(import.meta.url)), "schema.zed");
-            const schema = readFileSync(schemaPath, "utf-8");
-            await spicedb.writeSchema(schema);
-            console.log("SpiceDB schema written successfully.");
-          });
-
-        mem
-          .command("groups")
-          .description("List authorized groups for current subject")
-          .action(async () => {
-            const groups = await lookupAuthorizedGroups(spicedb, currentSubject);
-            if (groups.length === 0) {
-              console.log("No authorized groups.");
-              return;
-            }
-            console.log(`Authorized groups for ${currentSubject.type}:${currentSubject.id}:`);
-            for (const g of groups) {
-              console.log(`  - ${g}`);
-            }
-          });
-
-        mem
-          .command("add-member")
-          .description("Add a subject to a group")
-          .argument("<group-id>", "Group ID")
-          .argument("<subject-id>", "Subject ID")
-          .option("--type <type>", "Subject type (agent|person)", "person")
-          .action(async (groupId: string, subjectId: string, opts: { type: string }) => {
-            const subjectType = opts.type === "agent" ? "agent" : "person";
-            await ensureGroupMembership(spicedb, groupId, {
-              type: subjectType as "agent" | "person",
-              id: subjectId,
-            });
-            console.log(`Added ${subjectType}:${subjectId} to group:${groupId}`);
-          });
-
-        mem
-          .command("import")
-          .description("Import workspace markdown files (and optionally session transcripts) into Graphiti")
-          .option("--workspace <path>", "Workspace directory", join(homedir(), ".openclaw", "workspace"))
-          .option("--include-sessions", "Also import session JSONL transcripts", false)
-          .option("--sessions-only", "Only import session transcripts (skip workspace files)", false)
-          .option("--session-dir <path>", "Session transcripts directory", join(homedir(), ".openclaw", "agents", "main", "sessions"))
-          .option("--group <id>", "Target group for workspace files", cfg.graphiti.defaultGroupId)
-          .option("--dry-run", "List files without importing", false)
-          .action(async (opts: {
-            workspace: string;
-            includeSessions: boolean;
-            sessionsOnly: boolean;
-            sessionDir: string;
-            group: string;
-            dryRun: boolean;
-          }) => {
-            const workspacePath = resolve(opts.workspace);
-            const targetGroup = opts.group;
-            const importSessions = opts.includeSessions || opts.sessionsOnly;
-            const importWorkspace = !opts.sessionsOnly;
-
-            // Discover workspace markdown files
-            let mdFiles: string[] = [];
-            try {
-              const entries = await readdir(workspacePath);
-              mdFiles = entries.filter((f) => f.endsWith(".md")).sort();
-            } catch {
-              console.error(`Cannot read workspace directory: ${workspacePath}`);
-              return;
-            }
-
-            // Also check for memory/ subdirectory
-            try {
-              const memDir = join(workspacePath, "memory");
-              const memEntries = await readdir(memDir);
-              for (const f of memEntries) {
-                if (f.endsWith(".md")) {
-                  mdFiles.push(join("memory", f));
-                }
-              }
-            } catch {
-              // No memory/ subdirectory — that's fine
-            }
-
-            if (mdFiles.length === 0) {
-              console.log("No markdown files found in workspace.");
-              return;
-            }
-
-            console.log(`Found ${mdFiles.length} workspace file(s) in ${workspacePath}:`);
-            for (const f of mdFiles) {
-              const filePath = join(workspacePath, f);
-              const info = await stat(filePath);
-              console.log(`  ${f} (${info.size} bytes)`);
-            }
-
-            if (opts.dryRun) {
-              console.log("\n[dry-run] No files imported.");
-              if (importSessions) {
-                const sessionPath = resolve(opts.sessionDir);
-                try {
-                  const sessions = (await readdir(sessionPath)).filter((f) => f.endsWith(".jsonl"));
-                  console.log(`\nFound ${sessions.length} session transcript(s) in ${sessionPath}:`);
-                  for (const f of sessions) {
-                    const info = await stat(join(sessionPath, f));
-                    console.log(`  ${f} (${info.size} bytes)`);
-                  }
-                } catch {
-                  console.log(`\nCannot read session directory: ${sessionPath}`);
-                }
-              }
-              return;
-            }
-
-            // Import workspace files
-            if (importWorkspace) {
-              console.log(`\nImporting workspace files to group: ${targetGroup}`);
-              let imported = 0;
-              for (const f of mdFiles) {
-                const filePath = join(workspacePath, f);
-                const content = await readFile(filePath, "utf-8");
-                if (!content.trim()) {
-                  console.log(`  Skipping ${f} (empty)`);
-                  continue;
-                }
-                try {
-                  const result = await graphiti.addEpisode({
-                    name: f,
-                    episode_body: content,
-                    source_description: `Imported from OpenClaw workspace: ${f}`,
-                    group_id: targetGroup,
-                    source: "text",
-                  });
-                  await writeFragmentRelationships(spicedb, {
-                    fragmentId: result.episode_uuid,
-                    groupId: targetGroup,
-                    sharedBy: currentSubject,
-                  });
-                  console.log(`  Imported ${f} (${content.length} bytes) → episode ${result.episode_uuid}`);
-                  imported++;
-                } catch (err) {
-                  console.error(`  Failed to import ${f}: ${err instanceof Error ? err.message : String(err)}`);
-                }
-              }
-              console.log(`\nWorkspace import complete: ${imported}/${mdFiles.length} files.`);
-            }
-
-            // Import session transcripts
-            if (importSessions) {
-              const sessionPath = resolve(opts.sessionDir);
-              let jsonlFiles: string[] = [];
-              try {
-                jsonlFiles = (await readdir(sessionPath)).filter((f) => f.endsWith(".jsonl")).sort();
-              } catch {
-                console.error(`\nCannot read session directory: ${sessionPath}`);
-                return;
-              }
-
-              if (jsonlFiles.length === 0) {
-                console.log("\nNo session transcripts found.");
-                return;
-              }
-
-              console.log(`\nImporting ${jsonlFiles.length} session transcript(s)...`);
-              let sessionsImported = 0;
-              for (const f of jsonlFiles) {
-                const sessionId = basename(f, ".jsonl");
-                const sessionGroup = sessionGroupId(sessionId);
-                const filePath = join(sessionPath, f);
-                const raw = await readFile(filePath, "utf-8");
-                const lines = raw.split("\n").filter(Boolean);
-
-                // Extract user/assistant message text from JSONL
-                const conversationLines: string[] = [];
-                for (const line of lines) {
-                  try {
-                    const entry = JSON.parse(line) as Record<string, unknown>;
-                    // OpenClaw JSONL format: {"type":"message","message":{"role":"user","content":[...]}}
-                    const msg = (entry.type === "message" && entry.message && typeof entry.message === "object")
-                      ? entry.message as Record<string, unknown>
-                      : entry;
-                    const role = msg.role as string | undefined;
-                    if (role !== "user" && role !== "assistant") continue;
-                    const content = msg.content;
-                    let text = "";
-                    if (typeof content === "string") {
-                      text = content;
-                    } else if (Array.isArray(content)) {
-                      text = content
-                        .filter((b: unknown) =>
-                          typeof b === "object" && b !== null &&
-                          (b as Record<string, unknown>).type === "text" &&
-                          typeof (b as Record<string, unknown>).text === "string",
-                        )
-                        .map((b: unknown) => (b as Record<string, unknown>).text as string)
-                        .join("\n");
-                    }
-                    if (text && text.length >= 5 && !text.includes("<relevant-memories>") && !text.includes("<memory-tools>")) {
-                      const roleLabel = role === "user" ? "User" : "Assistant";
-                      conversationLines.push(`${roleLabel}: ${text}`);
-                    }
-                  } catch {
-                    // Skip malformed JSONL lines
-                  }
-                }
-
-                if (conversationLines.length === 0) {
-                  console.log(`  Skipping ${f} (no user/assistant messages)`);
-                  continue;
-                }
-
-                try {
-                  await ensureGroupMembership(spicedb, sessionGroup, currentSubject);
-                  const episodeBody = conversationLines.join("\n");
-                  const result = await graphiti.addEpisode({
-                    name: `session_${sessionId}`,
-                    episode_body: episodeBody,
-                    source_description: `Imported session transcript: ${sessionId}`,
-                    group_id: sessionGroup,
-                    source: "message",
-                  });
-                  await writeFragmentRelationships(spicedb, {
-                    fragmentId: result.episode_uuid,
-                    groupId: sessionGroup,
-                    sharedBy: currentSubject,
-                  });
-                  console.log(`  Imported ${f} (${conversationLines.length} messages) → episode ${result.episode_uuid} [group: ${sessionGroup}]`);
-                  sessionsImported++;
-                } catch (err) {
-                  console.error(`  Failed to import ${f}: ${err instanceof Error ? err.message : String(err)}`);
-                }
-              }
-              console.log(`\nSession import complete: ${sessionsImported}/${jsonlFiles.length} transcripts.`);
-            }
-          });
+        registerCommands(mem, {
+          graphiti,
+          spicedb,
+          cfg,
+          currentSubject,
+          getLastWriteToken: () => lastWriteToken,
+        });
       },
       { commands: ["graphiti-mem"] },
     );
@@ -711,10 +492,10 @@ const memoryGraphitiPlugin = {
     // ========================================================================
 
     if (cfg.autoRecall) {
-      api.on("before_agent_start", async (event) => {
-        // Track session ID from event context
-        if (event.ctx?.sessionKey) {
-          currentSessionId = event.ctx.sessionKey as string;
+      api.on("before_agent_start", async (event, ctx) => {
+        // Track session ID from hook context
+        if (ctx?.sessionKey) {
+          currentSessionId = ctx.sessionKey;
         }
 
         if (!event.prompt || event.prompt.length < 5) {
@@ -722,7 +503,7 @@ const memoryGraphitiPlugin = {
         }
 
         try {
-          const authorizedGroups = await lookupAuthorizedGroups(spicedb, currentSubject);
+          const authorizedGroups = await lookupAuthorizedGroups(spicedb, currentSubject, lastWriteToken);
           if (authorizedGroups.length === 0) {
             return;
           }
@@ -787,10 +568,10 @@ const memoryGraphitiPlugin = {
     }
 
     if (cfg.autoCapture) {
-      api.on("agent_end", async (event) => {
-        // Track session ID from event context
-        if (event.ctx?.sessionKey) {
-          currentSessionId = event.ctx.sessionKey as string;
+      api.on("agent_end", async (event, ctx) => {
+        // Track session ID from hook context
+        if (ctx?.sessionKey) {
+          currentSessionId = ctx.sessionKey;
         }
 
         if (!event.success || !event.messages || event.messages.length === 0) {
@@ -863,12 +644,13 @@ const memoryGraphitiPlugin = {
 
           if (isOwnSession) {
             try {
-              await ensureGroupMembership(spicedb, targetGroupId, currentSubject);
+              const token = await ensureGroupMembership(spicedb, targetGroupId, currentSubject);
+              if (token) lastWriteToken = token;
             } catch {
               // Best-effort
             }
           } else {
-            const allowed = await canWriteToGroup(spicedb, currentSubject, targetGroupId);
+            const allowed = await canWriteToGroup(spicedb, currentSubject, targetGroupId, lastWriteToken);
             if (!allowed) {
               api.logger.warn(`memory-graphiti: auto-capture denied for group ${targetGroupId}`);
               return;
@@ -883,11 +665,21 @@ const memoryGraphitiPlugin = {
             custom_extraction_instructions: cfg.customInstructions,
           });
 
-          await writeFragmentRelationships(spicedb, {
-            fragmentId: result.episode_uuid,
-            groupId: targetGroupId,
-            sharedBy: currentSubject,
-          });
+          // SpiceDB writes use the real UUID once Graphiti finishes processing
+          result.resolvedUuid
+            .then(async (realUuid) => {
+              const writeToken = await writeFragmentRelationships(spicedb, {
+                fragmentId: realUuid,
+                groupId: targetGroupId,
+                sharedBy: currentSubject,
+              });
+              if (writeToken) lastWriteToken = writeToken;
+            })
+            .catch((err) => {
+              api.logger.warn(
+                `memory-graphiti: deferred SpiceDB write (auto-capture) failed: ${err}`,
+              );
+            });
 
           api.logger.info(
             `memory-graphiti: auto-captured ${conversationLines.length} messages as batch episode to ${targetGroupId}`,
@@ -913,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");
@@ -927,11 +719,12 @@ const memoryGraphitiPlugin = {
         // Ensure current subject is a member of the default group
         if (spicedbOk) {
           try {
-            await ensureGroupMembership(
+            const token = await ensureGroupMembership(
               spicedb,
               cfg.graphiti.defaultGroupId,
               currentSubject,
             );
+            if (token) lastWriteToken = token;
           } catch {
             api.logger.warn("memory-graphiti: failed to ensure default group membership");
           }