@contextableai/openclaw-memory-graphiti 0.1.1

package/config.ts

@@ -0,0 +1,111 @@
+export type GraphitiMemoryConfig = {
+  spicedb: {
+    endpoint: string;
+    token: string;
+    insecure: boolean;
+  };
+  graphiti: {
+    endpoint: string;
+    defaultGroupId: string;
+  };
+  subjectType: "agent" | "person";
+  subjectId: string;
+  autoCapture: boolean;
+  autoRecall: boolean;
+  customInstructions: string;
+  maxCaptureMessages: number;
+};
+
+const DEFAULT_SPICEDB_ENDPOINT = "localhost:50051";
+const DEFAULT_GRAPHITI_ENDPOINT = "http://localhost:8000";
+const DEFAULT_GROUP_ID = "main";
+const DEFAULT_SUBJECT_TYPE = "agent";
+const DEFAULT_MAX_CAPTURE_MESSAGES = 10;
+
+const DEFAULT_CUSTOM_INSTRUCTIONS = `Extract key facts about:
+- Identity: names, roles, titles, contact info
+- Preferences: likes, dislikes, preferred tools/methods
+- Goals: objectives, plans, deadlines
+- Relationships: connections between people, teams, organizations
+- Decisions: choices made, reasoning, outcomes
+- Routines: habits, schedules, recurring patterns
+Do not extract: greetings, filler, meta-commentary about the conversation itself.`;
+
+function resolveEnvVars(value: string): string {
+  return value.replace(/\$\{([^}]+)\}/g, (_, envVar) => {
+    const envValue = process.env[envVar];
+    if (!envValue) {
+      throw new Error(`Environment variable ${envVar} is not set`);
+    }
+    return envValue;
+  });
+}
+
+function assertAllowedKeys(value: Record<string, unknown>, allowed: string[], label: string) {
+  const unknown = Object.keys(value).filter((key) => !allowed.includes(key));
+  if (unknown.length > 0) {
+    throw new Error(`${label} has unknown keys: ${unknown.join(", ")}`);
+  }
+}
+
+export const graphitiMemoryConfigSchema = {
+  parse(value: unknown): GraphitiMemoryConfig {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+      throw new Error("memory-graphiti config required");
+    }
+    const cfg = value as Record<string, unknown>;
+    assertAllowedKeys(
+      cfg,
+      [
+        "spicedb", "graphiti", "subjectType", "subjectId",
+        "autoCapture", "autoRecall", "customInstructions", "maxCaptureMessages",
+      ],
+      "memory-graphiti config",
+    );
+
+    // SpiceDB config
+    const spicedb = cfg.spicedb as Record<string, unknown> | undefined;
+    if (!spicedb || typeof spicedb.token !== "string") {
+      throw new Error("spicedb.token is required");
+    }
+    assertAllowedKeys(spicedb, ["endpoint", "token", "insecure"], "spicedb config");
+
+    // Graphiti config
+    const graphiti = (cfg.graphiti as Record<string, unknown>) ?? {};
+    assertAllowedKeys(graphiti, ["endpoint", "defaultGroupId"], "graphiti config");
+
+    // Subject
+    const subjectType = cfg.subjectType === "person" ? "person" : DEFAULT_SUBJECT_TYPE;
+    const subjectId =
+      typeof cfg.subjectId === "string" ? resolveEnvVars(cfg.subjectId) : "default";
+
+    return {
+      spicedb: {
+        endpoint:
+          typeof spicedb.endpoint === "string" ? spicedb.endpoint : DEFAULT_SPICEDB_ENDPOINT,
+        token: resolveEnvVars(spicedb.token),
+        insecure: spicedb.insecure !== false,
+      },
+      graphiti: {
+        endpoint:
+          typeof graphiti.endpoint === "string" ? graphiti.endpoint : DEFAULT_GRAPHITI_ENDPOINT,
+        defaultGroupId:
+          typeof graphiti.defaultGroupId === "string"
+            ? graphiti.defaultGroupId
+            : DEFAULT_GROUP_ID,
+      },
+      subjectType,
+      subjectId,
+      autoCapture: cfg.autoCapture !== false,
+      autoRecall: cfg.autoRecall !== false,
+      customInstructions:
+        typeof cfg.customInstructions === "string"
+          ? cfg.customInstructions
+          : DEFAULT_CUSTOM_INSTRUCTIONS,
+      maxCaptureMessages:
+        typeof cfg.maxCaptureMessages === "number" && cfg.maxCaptureMessages > 0
+          ? cfg.maxCaptureMessages
+          : DEFAULT_MAX_CAPTURE_MESSAGES,
+    };
+  },
+};

package/docker/.env.example

@@ -0,0 +1,66 @@
+# ===========================================================================
+# Required
+# ===========================================================================
+
+# OpenAI API key — Graphiti uses this for entity extraction and embeddings
+OPENAI_API_KEY=sk-proj-...
+
+# ===========================================================================
+# Optional (sensible defaults provided)
+# ===========================================================================
+
+# SpiceDB pre-shared authentication key
+SPICEDB_TOKEN=dev_token
+
+# PostgreSQL password (SpiceDB persistent datastore)
+SPICEDB_DB_PASSWORD=spicedb_dev
+
+# OpenClaw gateway image (default: locally built)
+# OPENCLAW_IMAGE=openclaw:local
+
+# OpenClaw gateway credentials (from your existing setup)
+# OPENCLAW_GATEWAY_TOKEN=
+# CLAUDE_AI_SESSION_KEY=
+# CLAUDE_WEB_SESSION_KEY=
+# CLAUDE_WEB_COOKIE=
+
+# OpenClaw directory mounts
+# OPENCLAW_CONFIG_DIR=./config
+# OPENCLAW_WORKSPACE_DIR=./workspace
+
+# Port overrides (if defaults conflict with other services)
+# OPENCLAW_GATEWAY_PORT=18789
+# OPENCLAW_BRIDGE_PORT=18790
+# FALKORDB_PORT=6379
+# FALKORDB_UI_PORT=3000
+# GRAPHITI_PORT=8000
+# SPICEDB_GRPC_PORT=50051
+# SPICEDB_HTTP_PORT=8443
+# SPICEDB_METRICS_PORT=9090
+# POSTGRES_PORT=5432
+
+# ===========================================================================
+# Plugin config reference
+# ===========================================================================
+#
+# When running via docker compose, services reach each other by hostname.
+# Configure the memory-graphiti plugin in OpenClaw with:
+#
+#   {
+#     "spicedb": {
+#       "endpoint": "spicedb:50051",
+#       "token": "${SPICEDB_TOKEN}",
+#       "insecure": true
+#     },
+#     "graphiti": {
+#       "endpoint": "http://graphiti-mcp:8000",
+#       "defaultGroupId": "main"
+#     }
+#   }
+#
+# Note: "spicedb" and "graphiti-mcp" are the Docker Compose service names.
+# Docker's built-in DNS resolves them to the correct container IPs.
+#
+# For E2E tests from outside Docker, use localhost with the mapped ports:
+#   GRAPHITI_ENDPOINT=http://localhost:8000
+#   SPICEDB_ENDPOINT=localhost:50051

package/docker/docker-compose.yml

@@ -0,0 +1,151 @@
+# Full-stack: OpenClaw gateway + memory-graphiti infrastructure
+#
+# All services share the same Docker network, so the gateway plugin
+# reaches Graphiti and SpiceDB by service hostname — no localhost hacks.
+#
+# Usage:
+#   cp .env.example .env        # Fill in OPENAI_API_KEY and other vars
+#   docker compose up -d        # Start everything
+#   docker compose logs -f      # Watch startup
+#
+# The gateway will be available at http://localhost:18789
+# FalkorDB web UI at http://localhost:3000
+#
+# To run without the gateway (infra only, for dev/testing):
+#   docker compose up -d falkordb graphiti-mcp spicedb
+
+services:
+  # --------------------------------------------------------------------------
+  # OpenClaw Gateway
+  # --------------------------------------------------------------------------
+  openclaw-gateway:
+    image: ${OPENCLAW_IMAGE:-openclaw:local}
+    environment:
+      HOME: /home/node
+      TERM: xterm-256color
+      OPENCLAW_GATEWAY_TOKEN: ${OPENCLAW_GATEWAY_TOKEN:-}
+      CLAUDE_AI_SESSION_KEY: ${CLAUDE_AI_SESSION_KEY:-}
+      CLAUDE_WEB_SESSION_KEY: ${CLAUDE_WEB_SESSION_KEY:-}
+      CLAUDE_WEB_COOKIE: ${CLAUDE_WEB_COOKIE:-}
+      # Memory-graphiti plugin will read these from the plugin config,
+      # but we also pass them as env vars for ${...} interpolation in config
+      OPENAI_API_KEY: ${OPENAI_API_KEY}
+      SPICEDB_TOKEN: ${SPICEDB_TOKEN:-dev_token}
+    volumes:
+      - ${OPENCLAW_CONFIG_DIR:-./config}:/home/node/.openclaw
+      - ${OPENCLAW_WORKSPACE_DIR:-./workspace}:/home/node/.openclaw/workspace
+    ports:
+      - "${OPENCLAW_GATEWAY_PORT:-18789}:18789"
+      - "${OPENCLAW_BRIDGE_PORT:-18790}:18790"
+    init: true
+    restart: unless-stopped
+    command:
+      [
+        "node",
+        "dist/index.js",
+        "gateway",
+        "--bind",
+        "${OPENCLAW_GATEWAY_BIND:-lan}",
+        "--port",
+        "18789",
+      ]
+    depends_on:
+      graphiti-mcp:
+        condition: service_healthy
+      spicedb:
+        condition: service_healthy
+
+  # --------------------------------------------------------------------------
+  # FalkorDB — graph database for Graphiti
+  # --------------------------------------------------------------------------
+  falkordb:
+    image: falkordb/falkordb:latest
+    ports:
+      - "${FALKORDB_PORT:-6379}:6379"    # FalkorDB/Redis protocol
+      - "${FALKORDB_UI_PORT:-3000}:3000" # FalkorDB web UI
+    volumes:
+      - falkordb-data:/data
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 5s
+      timeout: 3s
+      retries: 5
+
+  # --------------------------------------------------------------------------
+  # Graphiti MCP Server — knowledge graph API over HTTP
+  # --------------------------------------------------------------------------
+  graphiti-mcp:
+    image: ghcr.io/getzep/graphiti-mcp:latest
+    ports:
+      - "${GRAPHITI_PORT:-8000}:8000"    # MCP HTTP endpoint
+    environment:
+      - OPENAI_API_KEY=${OPENAI_API_KEY}
+      - FALKORDB_URI=redis://falkordb:6379
+    depends_on:
+      falkordb:
+        condition: service_healthy
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+
+  # --------------------------------------------------------------------------
+  # PostgreSQL — persistent datastore for SpiceDB
+  # --------------------------------------------------------------------------
+  postgres:
+    image: postgres:16-alpine
+    environment:
+      POSTGRES_USER: spicedb
+      POSTGRES_PASSWORD: ${SPICEDB_DB_PASSWORD:-spicedb_dev}
+      POSTGRES_DB: spicedb
+    ports:
+      - "${POSTGRES_PORT:-5432}:5432"
+    volumes:
+      - postgres-data:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U spicedb"]
+      interval: 5s
+      timeout: 3s
+      retries: 5
+
+  # --------------------------------------------------------------------------
+  # SpiceDB — authorization engine (persistent via PostgreSQL)
+  # --------------------------------------------------------------------------
+  spicedb-migrate:
+    image: authzed/spicedb:latest
+    command:
+      - migrate
+      - head
+      - --datastore-engine=postgres
+      - --datastore-conn-uri=postgres://spicedb:${SPICEDB_DB_PASSWORD:-spicedb_dev}@postgres:5432/spicedb?sslmode=disable
+    depends_on:
+      postgres:
+        condition: service_healthy
+
+  spicedb:
+    image: authzed/spicedb:latest
+    command:
+      - serve
+      - --grpc-preshared-key=${SPICEDB_TOKEN:-dev_token}
+      - --datastore-engine=postgres
+      - --datastore-conn-uri=postgres://spicedb:${SPICEDB_DB_PASSWORD:-spicedb_dev}@postgres:5432/spicedb?sslmode=disable
+      - --http-enabled=true
+    ports:
+      - "${SPICEDB_GRPC_PORT:-50051}:50051" # gRPC API
+      - "${SPICEDB_HTTP_PORT:-8443}:8443"   # HTTP gateway
+      - "${SPICEDB_METRICS_PORT:-9090}:9090" # Metrics/health
+    depends_on:
+      postgres:
+        condition: service_healthy
+      spicedb-migrate:
+        condition: service_completed_successfully
+    healthcheck:
+      test: ["CMD", "grpc_health_probe", "-addr=localhost:50051"]
+      interval: 5s
+      timeout: 3s
+      retries: 5
+
+volumes:
+  falkordb-data:
+  postgres-data:

package/graphiti.ts

@@ -0,0 +1,382 @@
+/**
+ * Graphiti MCP Server HTTP Client
+ *
+ * Communicates with the Graphiti MCP server via the MCP Streamable HTTP
+ * transport (JSON-RPC 2.0 over SSE). Handles session initialization,
+ * session ID tracking, and SSE response parsing.
+ *
+ * Wraps core tools: add_memory, search_nodes, search_memory_facts,
+ * get_episodes, delete_episode, get_status.
+ */
+
+import { randomUUID } from "node:crypto";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export type GraphitiEpisode = {
+  uuid: string;
+  name: string;
+  content: string;
+  source_description: string;
+  group_id: string;
+  created_at: string;
+};
+
+export type GraphitiNode = {
+  uuid: string;
+  name: string;
+  summary: string | null;
+  group_id: string;
+  labels: string[];
+  created_at: string | null;
+  attributes: Record<string, unknown>;
+};
+
+export type GraphitiFact = {
+  uuid: string;
+  fact: string;
+  name?: string;
+  source_node_uuid?: string;
+  target_node_uuid?: string;
+  source_node_name?: string;
+  target_node_name?: string;
+  group_id: string;
+  created_at: string;
+  [key: string]: unknown;
+};
+
+export type AddEpisodeResult = {
+  episode_uuid: string;
+};
+
+type JsonRpcRequest = {
+  jsonrpc: "2.0";
+  id: number;
+  method: string;
+  params?: Record<string, unknown>;
+};
+
+type JsonRpcResponse = {
+  jsonrpc: "2.0";
+  id: number;
+  result?: unknown;
+  error?: { code: number; message: string; data?: unknown };
+};
+
+// ============================================================================
+// Client
+// ============================================================================
+
+export class GraphitiClient {
+  private nextId = 1;
+  private sessionId: string | null = null;
+  private initPromise: Promise<void> | null = null;
+
+  constructor(private readonly endpoint: string) {}
+
+  // --------------------------------------------------------------------------
+  // MCP Session Lifecycle
+  // --------------------------------------------------------------------------
+
+  private async ensureInitialized(): Promise<void> {
+    if (this.sessionId) return;
+    if (!this.initPromise) {
+      this.initPromise = this.doInitialize();
+    }
+    return this.initPromise;
+  }
+
+  private async doInitialize(): Promise<void> {
+    const request: JsonRpcRequest = {
+      jsonrpc: "2.0",
+      id: this.nextId++,
+      method: "initialize",
+      params: {
+        protocolVersion: "2025-11-25",
+        capabilities: {},
+        clientInfo: { name: "openclaw-memory-graphiti", version: "1.0.0" },
+      },
+    };
+
+    const response = await fetch(`${this.endpoint}/mcp`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Accept: "application/json, text/event-stream",
+      },
+      body: JSON.stringify(request),
+    });
+
+    if (!response.ok) {
+      this.initPromise = null;
+      throw new Error(`Graphiti MCP init failed: ${response.status} ${response.statusText}`);
+    }
+
+    // Capture session ID from response header
+    this.sessionId = response.headers.get("mcp-session-id");
+
+    // Consume the SSE response body
+    await this.parseSseResponse(response);
+
+    // Send notifications/initialized (required by MCP protocol)
+    const headers: Record<string, string> = {
+      "Content-Type": "application/json",
+      Accept: "application/json, text/event-stream",
+    };
+    if (this.sessionId) {
+      headers["mcp-session-id"] = this.sessionId;
+    }
+    await fetch(`${this.endpoint}/mcp`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({ jsonrpc: "2.0", method: "notifications/initialized" }),
+    });
+  }
+
+  async close(): Promise<void> {
+    if (this.sessionId) {
+      try {
+        await fetch(`${this.endpoint}/mcp`, {
+          method: "DELETE",
+          headers: { "mcp-session-id": this.sessionId },
+        });
+      } catch {
+        // Ignore cleanup errors
+      }
+      this.sessionId = null;
+      this.initPromise = null;
+    }
+  }
+
+  // --------------------------------------------------------------------------
+  // JSON-RPC / SSE Transport
+  // --------------------------------------------------------------------------
+
+  private async callTool(name: string, args: Record<string, unknown> = {}): Promise<unknown> {
+    await this.ensureInitialized();
+
+    const request: JsonRpcRequest = {
+      jsonrpc: "2.0",
+      id: this.nextId++,
+      method: "tools/call",
+      params: { name, arguments: args },
+    };
+
+    const headers: Record<string, string> = {
+      "Content-Type": "application/json",
+      Accept: "application/json, text/event-stream",
+    };
+    if (this.sessionId) {
+      headers["mcp-session-id"] = this.sessionId;
+    }
+
+    const response = await fetch(`${this.endpoint}/mcp`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(request),
+    });
+
+    if (!response.ok) {
+      throw new Error(`Graphiti MCP server error: ${response.status} ${response.statusText}`);
+    }
+
+    const json = await this.parseResponse(response);
+
+    if (json.error) {
+      throw new Error(`Graphiti tool ${name} failed: ${json.error.message}`);
+    }
+
+    return json.result;
+  }
+
+  private async parseResponse(response: Response): Promise<JsonRpcResponse> {
+    const contentType = response.headers.get("content-type") ?? "";
+    if (contentType.includes("text/event-stream")) {
+      return this.parseSseResponse(response);
+    }
+    return (await response.json()) as JsonRpcResponse;
+  }
+
+  private async parseSseResponse(response: Response): Promise<JsonRpcResponse> {
+    const text = await response.text();
+    for (const line of text.split("\n")) {
+      if (line.startsWith("data: ")) {
+        const data = line.slice(6).trim();
+        if (data) {
+          return JSON.parse(data) as JsonRpcResponse;
+        }
+      }
+    }
+    throw new Error("No JSON-RPC message found in SSE response");
+  }
+
+  // --------------------------------------------------------------------------
+  // Health
+  // --------------------------------------------------------------------------
+
+  async healthCheck(): Promise<boolean> {
+    try {
+      const response = await fetch(`${this.endpoint}/health`);
+      return response.ok;
+    } catch {
+      return false;
+    }
+  }
+
+  async getStatus(): Promise<unknown> {
+    return this.callTool("get_status");
+  }
+
+  // --------------------------------------------------------------------------
+  // Episodes
+  // --------------------------------------------------------------------------
+
+  async addEpisode(params: {
+    name: string;
+    episode_body: string;
+    source_description?: string;
+    group_id?: string;
+    source?: string;
+    /**
+     * Custom extraction instructions for Graphiti's LLM entity extraction.
+     * The MCP server doesn't expose this parameter, so we prepend the
+     * instructions to episode_body with clear delimiters. Graphiti's
+     * extraction prompts include the full episode content, so the LLM
+     * will see these instructions inline alongside the actual content.
+     */
+    custom_extraction_instructions?: string;
+    /** @deprecated The MCP server's uuid param is for re-processing existing episodes */
+    uuid?: string;
+    /** @deprecated No longer supported by the Graphiti MCP server */
+    reference_time?: string;
+  }): Promise<AddEpisodeResult> {
+    // 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();
+
+    // Prepend custom extraction instructions to episode_body since the MCP
+    // server doesn't support custom_extraction_instructions as a parameter.
+    // The extraction LLM sees the full episode content, so inline instructions work.
+    let effectiveBody = params.episode_body;
+    if (params.custom_extraction_instructions) {
+      effectiveBody =
+        `[Extraction Instructions]\n${params.custom_extraction_instructions}\n[End Instructions]\n\n${params.episode_body}`;
+    }
+
+    const args: Record<string, unknown> = {
+      name: params.name,
+      episode_body: effectiveBody,
+    };
+    if (params.group_id) {
+      args.group_id = params.group_id;
+    }
+    if (params.source) {
+      args.source = params.source;
+    }
+    if (params.source_description) {
+      args.source_description = params.source_description;
+    }
+
+    await this.callTool("add_memory", args);
+    return { episode_uuid: trackingUuid };
+  }
+
+  async getEpisodes(groupId: string, lastN: number): Promise<GraphitiEpisode[]> {
+    const result = await this.callTool("get_episodes", {
+      group_ids: [groupId],
+      max_episodes: lastN,
+    });
+    return parseToolResult<GraphitiEpisode[]>(result, "episodes");
+  }
+
+  async deleteEpisode(episodeUuid: string): Promise<void> {
+    await this.callTool("delete_episode", { uuid: episodeUuid });
+  }
+
+  // --------------------------------------------------------------------------
+  // Search
+  // --------------------------------------------------------------------------
+
+  async searchNodes(params: {
+    query: string;
+    group_id?: string;
+    group_ids?: string[];
+    limit?: number;
+  }): Promise<GraphitiNode[]> {
+    const args: Record<string, unknown> = {
+      query: params.query,
+    };
+    const groupIds = params.group_ids ?? (params.group_id ? [params.group_id] : undefined);
+    if (groupIds) {
+      args.group_ids = groupIds;
+    }
+    if (params.limit !== undefined) {
+      args.max_nodes = params.limit;
+    }
+
+    const result = await this.callTool("search_nodes", args);
+    return parseToolResult<GraphitiNode[]>(result, "nodes");
+  }
+
+  async searchFacts(params: {
+    query: string;
+    group_id?: string;
+    group_ids?: string[];
+    limit?: number;
+    /** @deprecated No longer supported by the Graphiti MCP server */
+    created_after?: string;
+  }): Promise<GraphitiFact[]> {
+    const args: Record<string, unknown> = {
+      query: params.query,
+    };
+    const groupIds = params.group_ids ?? (params.group_id ? [params.group_id] : undefined);
+    if (groupIds) {
+      args.group_ids = groupIds;
+    }
+    if (params.limit !== undefined) {
+      args.max_facts = params.limit;
+    }
+
+    const result = await this.callTool("search_memory_facts", args);
+    return parseToolResult<GraphitiFact[]>(result, "facts");
+  }
+}
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+/**
+ * Extract a typed result from an MCP tool response.
+ * The response is typically wrapped in content blocks:
+ *   { content: [{ type: "text", text: "{ \"nodes\": [...] }" }] }
+ * This function unwraps the content block, parses the JSON, and extracts
+ * the named field (e.g. "nodes", "facts", "episodes").
+ */
+function parseToolResult<T>(result: unknown, key: string): T {
+  const parsed = parseJsonResult<Record<string, unknown>>(result);
+  if (parsed && typeof parsed === "object" && key in parsed) {
+    return parsed[key] as T;
+  }
+  return [] as unknown as T;
+}
+
+function parseJsonResult<T>(result: unknown): T {
+  if (typeof result === "string") {
+    return JSON.parse(result) as T;
+  }
+  // MCP tool results are typically wrapped in content blocks
+  if (result && typeof result === "object" && "content" in result) {
+    const content = (result as Record<string, unknown>).content;
+    if (Array.isArray(content) && content.length > 0) {
+      const first = content[0] as Record<string, unknown>;
+      if (first.type === "text" && typeof first.text === "string") {
+        return JSON.parse(first.text) as T;
+      }
+    }
+  }
+  return result as T;
+}