@contextableai/openclaw-memory-graphiti 0.2.5 → 0.2.7

package/config.ts

@@ -55,10 +55,11 @@ function assertAllowedKeys(value: Record<string, unknown>, allowed: string[], la
 
 export const graphitiMemoryConfigSchema = {
   parse(value: unknown): GraphitiMemoryConfig {
-    if (!value || typeof value !== "object" || Array.isArray(value)) {
-      throw new Error("openclaw-memory-graphiti config required");
+    if (Array.isArray(value)) {
+      throw new Error("openclaw-memory-graphiti config must be an object, not an array");
     }
-    const cfg = value as Record<string, unknown>;
+    // Accept undefined/null (installer writes no config key) — treat as empty {}
+    const cfg = (value && typeof value === "object" ? value : {}) as Record<string, unknown>;
     assertAllowedKeys(
       cfg,
       [

package/graphiti.ts

@@ -80,7 +80,7 @@ export class GraphitiClient {
   /** Polling interval (ms) for UUID resolution after addEpisode. */
   uuidPollIntervalMs = 3000;
   /** Max polling attempts for UUID resolution (total wait = interval * attempts). */
-  uuidPollMaxAttempts = 30;
+  uuidPollMaxAttempts = 80;
 
   constructor(private readonly endpoint: string) {}
 

package/index.ts

@@ -12,6 +12,7 @@
 
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
 import { Type } from "@sinclair/typebox";
+import { randomUUID } from "node:crypto";
 import { readFileSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -117,9 +118,9 @@ const memoryGraphitiPlugin = {
         name: "memory_recall",
         label: "Memory Recall",
         description:
-          "Search through memories using the knowledge graph. Returns entities and facts the current user is authorized to see. Supports session, long-term, or combined scope.",
+          "Search through memories using the knowledge graph. Returns entities and facts the current user is authorized to see. Supports session, long-term, or combined scope. REQUIRES a search query.",
         parameters: Type.Object({
-          query: Type.String({ description: "Search query" }),
+          query: Type.String({ description: "REQUIRED: Search query for semantic matching" }),
           limit: Type.Optional(Type.Number({ description: "Max results (default: 10)" })),
           scope: Type.Optional(
             Type.Union(
@@ -249,7 +250,7 @@ const memoryGraphitiPlugin = {
             Type.Array(Type.String(), { description: "Person/agent IDs involved in this memory" }),
           ),
           group_id: Type.Optional(
-            Type.String({ description: "Target group for this memory (default: configured group)" }),
+            Type.String({ description: "Target group ID (optional, uses your default group if omitted)" }),
           ),
           longTerm: Type.Optional(
             Type.Boolean({ description: "Store as long-term memory (default: true). Set to false for session-scoped." }),
@@ -270,10 +271,22 @@ const memoryGraphitiPlugin = {
             longTerm?: boolean;
           };
 
+          // Sanitize group_id: SpiceDB requires alphanumeric + _|\\-=+ only (no spaces!)
+          const sanitizeGroupId = (id?: string): string | undefined => {
+            if (!id) return undefined;
+            const trimmed = id.trim();
+            // If it looks like a description rather than an ID, ignore it
+            if (trimmed.includes(' ') || trimmed.toLowerCase().includes('configured')) {
+              return undefined;
+            }
+            return trimmed;
+          };
+
           // Resolve target group: explicit > longTerm flag > default
           let targetGroupId: string;
-          if (group_id) {
-            targetGroupId = group_id;
+          const sanitizedGroupId = sanitizeGroupId(group_id);
+          if (sanitizedGroupId) {
+            targetGroupId = sanitizedGroupId;
           } else if (!longTerm && currentSessionId) {
             targetGroupId = sessionGroupId(currentSessionId);
           } else {
@@ -312,8 +325,10 @@ const memoryGraphitiPlugin = {
           }
 
           // 1. Add episode to Graphiti
+          // Generate unique episode name to avoid collisions
+          const episodeName = `memory_${randomUUID()}`;
           const result = await graphiti.addEpisode({
-            name: `memory_${Date.now()}`,
+            name: episodeName,
             episode_body: content,
             source_description,
             group_id: targetGroupId,
@@ -682,8 +697,10 @@ const memoryGraphitiPlugin = {
             }
           }
 
+          // Generate unique episode name to avoid collisions
+          const episodeName = `auto_capture_${randomUUID()}`;
           const result = await graphiti.addEpisode({
-            name: `auto_capture_${Date.now()}`,
+            name: episodeName,
             episode_body: episodeBody,
             source_description: "auto-captured conversation",
             group_id: targetGroupId,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contextableai/openclaw-memory-graphiti",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "description": "OpenClaw two-layer memory plugin: SpiceDB authorization + Graphiti knowledge graph",
   "type": "module",
   "license": "MIT",

package/scripts/dev-start.sh

@@ -5,15 +5,25 @@
 # Services run in the background; logs go to .dev/logs/.
 # PID files are written to .dev/pids/.
 #
-# Environment variables (all optional):
-#   OPENAI_API_KEY        Required by Graphiti for entity extraction
+# Environment variables:
+#   OPENAI_API_KEY        Required by Graphiti for entity extraction (unless using local models)
 #   SPICEDB_TOKEN         Pre-shared key (default: dev_token)
 #   SPICEDB_PORT          gRPC port (default: 50051)
 #   SPICEDB_DATASTORE     "memory" (default) or "postgres"
 #   SPICEDB_DB_URI        Postgres connection URI (when SPICEDB_DATASTORE=postgres)
 #   FALKORDB_PORT         Redis port (default: 6379)
 #   GRAPHITI_PORT         HTTP port (default: 8000)
+#   GRAPHITI_PATH         Path to Graphiti git clone (default: ../graphiti)
 #   EPISODE_ID_PREFIX     Prefix for Graphiti episode UUIDs (default: epi-)
+#
+# Optional: Use local models instead of OpenAI
+#   LLM_PROVIDER          "openai_generic" (enables custom LLM endpoint)
+#   LLM_MODEL             Model name (e.g., "nvidia/Qwen3-Next-80B-A3B-Instruct-NVFP4")
+#   LLM_API_URL           Custom LLM endpoint (e.g., "http://dgx-spark:8000/v1")
+#   EMBEDDER_MODEL        Embedding model (e.g., "nomic-embed-text:v1.5")
+#   EMBEDDER_DIMENSIONS   Embedding dimensions (e.g., 768 for nomic, 1536 for OpenAI)
+#   EMBEDDER_API_URL      Custom embedder endpoint (e.g., "http://minisforum:11434/v1")
+#   RERANKER_PROVIDER     Reranker provider: "openai", "gemini", or "bge" (default: bge)
 # -------------------------------------------------------------------
 set -euo pipefail
 
@@ -35,6 +45,17 @@ SPICEDB_DATASTORE="${SPICEDB_DATASTORE:-memory}"
 SPICEDB_DB_URI="${SPICEDB_DB_URI:-postgres://spicedb:spicedb_dev@127.0.0.1:5432/spicedb?sslmode=disable}"
 FALKORDB_PORT="${FALKORDB_PORT:-6379}"
 GRAPHITI_PORT="${GRAPHITI_PORT:-8000}"
+GRAPHITI_PATH="${GRAPHITI_PATH:-$PROJECT_DIR/../graphiti}"
+
+# Local model endpoints (for your dev environment)
+LLM_PROVIDER="${LLM_PROVIDER:-openai_generic}"
+LLM_MODEL="${LLM_MODEL:-nvidia/Qwen3-Next-80B-A3B-Instruct-NVFP4}"
+LLM_API_URL="${LLM_API_URL:-http://dgx-spark:8000/v1}"
+LLM_MAX_TOKENS="${LLM_MAX_TOKENS:-8192}"
+EMBEDDER_MODEL="${EMBEDDER_MODEL:-nomic-embed-text:v1.5}"
+EMBEDDER_DIMENSIONS="${EMBEDDER_DIMENSIONS:-768}"
+EMBEDDER_API_URL="${EMBEDDER_API_URL:-http://minisforum:11434/v1}"
+RERANKER_PROVIDER="${RERANKER_PROVIDER:-bge}"
 
 mkdir -p "$DEV_DIR/logs" "$DEV_DIR/pids" "$DEV_DIR/data/falkordb"
 
@@ -71,8 +92,9 @@ else
     --port "$FALKORDB_PORT" \
     --dir "$DEV_DIR/data/falkordb" \
     --daemonize no \
-    --save "" \
-    --appendonly no \
+    --save "300 10 60 1000" \
+    --appendonly yes \
+    --appendfsync everysec \
     --loglevel notice \
     > "$DEV_DIR/logs/falkordb.log" 2>&1 &
   echo $! > "$DEV_DIR/pids/falkordb.pid"
@@ -178,23 +200,30 @@ fi
 if is_running "$DEV_DIR/pids/graphiti.pid"; then
   echo "==> Graphiti MCP server already running (pid $(cat "$DEV_DIR/pids/graphiti.pid"))"
 else
-  if [ -z "${OPENAI_API_KEY:-}" ]; then
-    echo ""
-    echo "WARNING: OPENAI_API_KEY is not set."
-    echo "Graphiti needs it for entity extraction and embeddings."
-    echo "Set it in .env or export it before running this script."
-    echo ""
-  fi
-
   echo "==> Starting Graphiti MCP server on port $GRAPHITI_PORT..."
+  echo "    LLM:               $LLM_PROVIDER / $LLM_MODEL"
+  echo "    LLM endpoint:      $LLM_API_URL"
+  echo "    Embedder:          $EMBEDDER_MODEL (${EMBEDDER_DIMENSIONS}d)"
+  echo "    Embedder endpoint: $EMBEDDER_API_URL"
+  echo "    Reranker:          $RERANKER_PROVIDER"
 
-  GRAPHITI_DIR="$DEV_DIR/graphiti/mcp_server"
+  GRAPHITI_DIR="$GRAPHITI_PATH/mcp_server"
 
   # Set environment for Graphiti
-  export OPENAI_API_KEY="${OPENAI_API_KEY:-}"
+  export OPENAI_API_KEY="${OPENAI_API_KEY:-not-needed}"
   export FALKORDB_URI="redis://localhost:$FALKORDB_PORT"
   export EPISODE_ID_PREFIX="${EPISODE_ID_PREFIX:-epi-}"
 
+  # Export local model configuration
+  export LLM_PROVIDER
+  export LLM_MODEL
+  export LLM_API_URL
+  export LLM_MAX_TOKENS
+  export EMBEDDER_MODEL
+  export EMBEDDER_DIMENSIONS
+  export EMBEDDER_API_URL
+  export RERANKER_PROVIDER
+
   cd "$GRAPHITI_DIR"
   uv run main.py \
     --transport http \