@contextableai/openclaw-memory-rebac 0.1.0

package/backends/graphiti.ts

@@ -0,0 +1,345 @@
+/**
+ * GraphitiBackend — MemoryBackend implementation backed by the Graphiti FastAPI REST server.
+ *
+ * Graphiti communicates via standard HTTP REST endpoints.
+ * Episodes are processed asynchronously by Graphiti's LLM pipeline;
+ * the real server-side UUID is discovered by polling GET /episodes/{group_id}.
+ *
+ * store() returns immediately; fragmentId resolves once Graphiti finishes
+ * processing and the UUID becomes visible in the episodes list.
+ */
+
+import { randomUUID } from "node:crypto";
+import type { Command } from "commander";
+import type {
+  MemoryBackend,
+  SearchResult,
+  StoreResult,
+  ConversationTurn,
+  BackendDataset,
+} from "../backend.js";
+
+// ============================================================================
+// Types (Graphiti REST API)
+// ============================================================================
+
+/** Matches the server's Message schema (from /openapi.json). */
+type GraphitiMessage = {
+  content: string;
+  role_type: "user" | "assistant" | "system";
+  role: string | null;
+  name?: string;
+  timestamp?: string;
+  source_description?: string;
+};
+
+type AddMessagesRequest = {
+  group_id: string;
+  messages: GraphitiMessage[];
+};
+
+type GraphitiEpisode = {
+  uuid: string;
+  name: string;
+  content: string;
+  source_description: string;
+  group_id: string;
+  created_at: string;
+};
+
+type FactResult = {
+  uuid: string;
+  name: string;
+  fact: string;
+  valid_at: string | null;
+  invalid_at: string | null;
+  created_at: string;
+  expired_at: string | null;
+};
+
+type SearchRequest = {
+  group_ids: string[];
+  query: string;
+  max_facts?: number;
+};
+
+type SearchResults = {
+  facts: FactResult[];
+};
+
+type GraphitiResult = {
+  message: string;
+  success: boolean;
+};
+
+// ============================================================================
+// GraphitiBackend
+// ============================================================================
+
+export type GraphitiConfig = {
+  endpoint: string;
+  defaultGroupId: string;
+  uuidPollIntervalMs: number;
+  uuidPollMaxAttempts: number;
+  requestTimeoutMs?: number;
+  customInstructions: string;
+};
+
+export class GraphitiBackend implements MemoryBackend {
+  readonly name = "graphiti";
+
+  readonly uuidPollIntervalMs: number;
+  readonly uuidPollMaxAttempts: number;
+  private readonly requestTimeoutMs: number;
+
+  constructor(private readonly config: GraphitiConfig) {
+    this.uuidPollIntervalMs = config.uuidPollIntervalMs;
+    this.uuidPollMaxAttempts = config.uuidPollMaxAttempts;
+    this.requestTimeoutMs = config.requestTimeoutMs ?? 30000;
+  }
+
+  // --------------------------------------------------------------------------
+  // REST transport
+  // --------------------------------------------------------------------------
+
+  private async restCall<T>(
+    method: "GET" | "POST" | "DELETE",
+    path: string,
+    body?: unknown,
+  ): Promise<T> {
+    const url = `${this.config.endpoint}${path}`;
+    const opts: RequestInit = {
+      method,
+      headers: { "Content-Type": "application/json" },
+      signal: AbortSignal.timeout(this.requestTimeoutMs),
+    };
+    if (body !== undefined) {
+      opts.body = JSON.stringify(body);
+    }
+    const response = await fetch(url, opts);
+    if (!response.ok) {
+      const text = await response.text().catch(() => "");
+      throw new Error(`Graphiti REST ${method} ${path} failed: ${response.status} ${text}`);
+    }
+    const ct = response.headers.get("content-type") ?? "";
+    if (ct.includes("application/json")) {
+      return (await response.json()) as T;
+    }
+    return {} as T;
+  }
+
+  // --------------------------------------------------------------------------
+  // MemoryBackend implementation
+  // --------------------------------------------------------------------------
+
+  async store(params: {
+    content: string;
+    groupId: string;
+    sourceDescription?: string;
+    customPrompt?: string;
+  }): Promise<StoreResult> {
+    const episodeName = `memory_${randomUUID()}`;
+    let effectiveBody = params.content;
+    if (params.customPrompt) {
+      effectiveBody = `[Extraction Instructions]\n${params.customPrompt}\n[End Instructions]\n\n${params.content}`;
+    }
+
+    const request: AddMessagesRequest = {
+      group_id: params.groupId,
+      messages: [
+        {
+          name: episodeName,
+          content: effectiveBody,
+          timestamp: new Date().toISOString(),
+          role_type: "user",
+          role: "user",
+          source_description: params.sourceDescription,
+        },
+      ],
+    };
+
+    await this.restCall<GraphitiResult>("POST", "/messages", request);
+
+    // POST /messages returns 202 (async processing).
+    // Poll GET /episodes until the episode appears, then return its real UUID.
+    const fragmentId = this.resolveEpisodeUuid(episodeName, params.groupId);
+    fragmentId.catch(() => {}); // Prevent unhandled rejection if caller drops it
+
+    return { fragmentId };
+  }
+
+  private async resolveEpisodeUuid(name: string, groupId: string): Promise<string> {
+    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 {
+        // Transient error — keep polling
+      }
+    }
+    throw new Error(`Timed out resolving episode UUID for "${name}" in group "${groupId}"`);
+  }
+
+  async searchGroup(params: {
+    query: string;
+    groupId: string;
+    limit: number;
+    sessionId?: string;
+  }): Promise<SearchResult[]> {
+    const { query, groupId, limit } = params;
+
+    const searchRequest: SearchRequest = {
+      group_ids: [groupId],
+      query,
+      max_facts: limit,
+    };
+
+    const response = await this.restCall<SearchResults>("POST", "/search", searchRequest);
+    const facts = response.facts ?? [];
+
+    return facts.map((f) => ({
+      type: "fact" as const,
+      uuid: f.uuid,
+      group_id: groupId,
+      summary: f.fact,
+      context: f.name,
+      created_at: f.created_at,
+    }));
+  }
+
+  async getConversationHistory(sessionId: string, lastN = 10): Promise<ConversationTurn[]> {
+    const sessionGroup = `session-${sessionId.replace(/[^a-zA-Z0-9_-]/g, "-")}`;
+    try {
+      const episodes = await this.getEpisodes(sessionGroup, lastN);
+      return episodes.map((ep) => ({
+        query: ep.name,
+        answer: ep.content,
+        created_at: ep.created_at,
+      }));
+    } catch {
+      return [];
+    }
+  }
+
+  async healthCheck(): Promise<boolean> {
+    try {
+      const response = await fetch(`${this.config.endpoint}/healthcheck`, {
+        signal: AbortSignal.timeout(5000),
+      });
+      return response.ok;
+    } catch {
+      return false;
+    }
+  }
+
+  async getStatus(): Promise<Record<string, unknown>> {
+    return {
+      backend: "graphiti",
+      endpoint: this.config.endpoint,
+      healthy: await this.healthCheck(),
+    };
+  }
+
+  async deleteGroup(groupId: string): Promise<void> {
+    await this.restCall<GraphitiResult>(
+      "DELETE",
+      `/group/${encodeURIComponent(groupId)}`,
+    );
+  }
+
+  async listGroups(): Promise<BackendDataset[]> {
+    // Graphiti has no list-groups API; the CLI can query SpiceDB for this
+    return [];
+  }
+
+  async deleteFragment(uuid: string): Promise<boolean> {
+    await this.restCall<GraphitiResult>(
+      "DELETE",
+      `/episode/${encodeURIComponent(uuid)}`,
+    );
+    return true;
+  }
+
+  // --------------------------------------------------------------------------
+  // Graphiti-specific helpers (used by CLI commands and UUID polling)
+  // --------------------------------------------------------------------------
+
+  async getEpisodes(groupId: string, lastN: number): Promise<GraphitiEpisode[]> {
+    return this.restCall<GraphitiEpisode[]>(
+      "GET",
+      `/episodes/${encodeURIComponent(groupId)}?last_n=${lastN}`,
+    );
+  }
+
+  async getEntityEdge(uuid: string): Promise<FactResult> {
+    return this.restCall<FactResult>(
+      "GET",
+      `/entity-edge/${encodeURIComponent(uuid)}`,
+    );
+  }
+
+  // --------------------------------------------------------------------------
+  // Backend-specific CLI commands
+  // --------------------------------------------------------------------------
+
+  registerCliCommands(cmd: Command): void {
+    cmd
+      .command("episodes")
+      .description("[graphiti] List recent episodes for a group")
+      .option("--last <n>", "Number of episodes", "10")
+      .option("--group <id>", "Group ID")
+      .action(async (opts: { last: string; group?: string }) => {
+        const groupId = opts.group ?? this.config.defaultGroupId;
+        const episodes = await this.getEpisodes(groupId, parseInt(opts.last));
+        console.log(JSON.stringify(episodes, null, 2));
+      });
+
+    cmd
+      .command("fact")
+      .description("[graphiti] Get a specific fact (entity edge) by UUID")
+      .argument("<uuid>", "Fact UUID")
+      .action(async (uuid: string) => {
+        try {
+          const fact = await this.getEntityEdge(uuid);
+          console.log(JSON.stringify(fact, null, 2));
+        } catch (err) {
+          console.error(`Failed to get fact: ${err instanceof Error ? err.message : String(err)}`);
+        }
+      });
+
+    cmd
+      .command("clear-graph")
+      .description("[graphiti] Clear graph data for a group (destructive!)")
+      .option("--group <id...>", "Group ID(s)")
+      .option("--confirm", "Required safety flag", false)
+      .action(async (opts: { group?: string[]; confirm: boolean }) => {
+        if (!opts.confirm) {
+          console.log("Destructive operation. Pass --confirm to proceed.");
+          return;
+        }
+        const groups = opts.group ?? [];
+        if (groups.length === 0) {
+          console.log("No groups specified. Use --group <id> to specify groups.");
+          return;
+        }
+        for (const g of groups) {
+          await this.deleteGroup(g);
+          console.log(`Cleared group: ${g}`);
+        }
+      });
+  }
+}
+
+// ============================================================================
+// Backend module exports (used by backends/registry.ts)
+// ============================================================================
+
+import graphitiDefaults from "./graphiti.defaults.json" with { type: "json" };
+
+export const defaults: Record<string, unknown> = graphitiDefaults;
+
+export function create(config: Record<string, unknown>): MemoryBackend {
+  return new GraphitiBackend(config as GraphitiConfig);
+}

package/backends/registry.ts

@@ -0,0 +1,36 @@
+/**
+ * Backend registry — loaded dynamically from backends.json.
+ *
+ * Call initRegistry() once (e.g. at the start of register()) before using
+ * backendRegistry or createBackend(). No backend names appear in this file.
+ *
+ * To add a new backend:
+ *   1. Create backends/<name>.ts  (exports `defaults` and `create`)
+ *   2. Create backends/<name>.defaults.json
+ *   3. Add `"<name>": "./<name>.js"` to backends/backends.json
+ *   No TypeScript changes needed anywhere else.
+ */
+
+import backendsJson from "./backends.json" with { type: "json" };
+import type { MemoryBackend } from "../backend.js";
+
+export type BackendModule = {
+  create: (config: Record<string, unknown>) => MemoryBackend;
+  defaults: Record<string, unknown>;
+};
+
+// Mutable backing store — populated by initRegistry().
+// backendRegistry is a live reference to the same object.
+const _registry: Record<string, BackendModule> = {};
+
+export async function initRegistry(): Promise<void> {
+  if (Object.keys(_registry).length > 0) return;
+  for (const [name, modulePath] of Object.entries(backendsJson as Record<string, string>)) {
+    const url = new URL(modulePath, import.meta.url);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const mod = await import(url.href) as any;
+    _registry[name] = mod as BackendModule;
+  }
+}
+
+export const backendRegistry: Readonly<Record<string, BackendModule>> = _registry;

package/bin/rebac-mem.ts

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+/**
+ * Standalone CLI entry point for rebac-mem commands.
+ *
+ * Reads config from environment variables and/or a JSON config file,
+ * instantiates SpiceDB + selected backend, and exposes the same commands
+ * as the OpenClaw plugin — without requiring a running gateway.
+ *
+ * Usage:
+ *   npx tsx bin/rebac-mem.ts <command> [options]
+ *   npm run cli -- <command> [options]
+ *
+ * Config priority (highest first):
+ *   1. Environment variables
+ *   2. rebac-mem.config.json (current directory)
+ *   3. ~/.config/rebac-mem/config.json
+ *   4. Defaults
+ */
+
+import { Command } from "commander";
+import { readFileSync, existsSync } from "node:fs";
+import { resolve, join } from "node:path";
+import { homedir } from "node:os";
+import { rebacMemoryConfigSchema, createBackend } from "../config.js";
+import { SpiceDbClient } from "../spicedb.js";
+import { registerCommands } from "../cli.js";
+
+// ============================================================================
+// Config loading
+// ============================================================================
+
+function loadConfigFile(configPath?: string): Record<string, unknown> | null {
+  const candidates = configPath
+    ? [resolve(configPath)]
+    : [
+        resolve("rebac-mem.config.json"),
+        join(homedir(), ".config", "rebac-mem", "config.json"),
+      ];
+  for (const path of candidates) {
+    if (existsSync(path)) {
+      try {
+        return JSON.parse(readFileSync(path, "utf-8")) as Record<string, unknown>;
+      } catch (err) {
+        console.error(`Failed to parse config file ${path}: ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
+      }
+    }
+  }
+  return null;
+}
+
+function loadConfigFromEnv(): Record<string, unknown> {
+  const env = process.env;
+  const config: Record<string, unknown> = {};
+
+  if (env.REBAC_MEM_BACKEND) config.backend = env.REBAC_MEM_BACKEND;
+
+  // SpiceDB config
+  const spicedb: Record<string, unknown> = {};
+  if (env.REBAC_MEM_SPICEDB_TOKEN ?? env.SPICEDB_TOKEN)
+    spicedb.token = env.REBAC_MEM_SPICEDB_TOKEN ?? env.SPICEDB_TOKEN;
+  if (env.REBAC_MEM_SPICEDB_ENDPOINT ?? env.SPICEDB_ENDPOINT)
+    spicedb.endpoint = env.REBAC_MEM_SPICEDB_ENDPOINT ?? env.SPICEDB_ENDPOINT;
+  if (env.REBAC_MEM_SPICEDB_INSECURE)
+    spicedb.insecure = env.REBAC_MEM_SPICEDB_INSECURE !== "false";
+  if (Object.keys(spicedb).length > 0) config.spicedb = spicedb;
+
+  // Graphiti config
+  const graphiti: Record<string, unknown> = {};
+  if (env.REBAC_MEM_GRAPHITI_ENDPOINT ?? env.GRAPHITI_ENDPOINT)
+    graphiti.endpoint = env.REBAC_MEM_GRAPHITI_ENDPOINT ?? env.GRAPHITI_ENDPOINT;
+  if (env.REBAC_MEM_DEFAULT_GROUP_ID)
+    graphiti.defaultGroupId = env.REBAC_MEM_DEFAULT_GROUP_ID;
+  if (Object.keys(graphiti).length > 0) config.graphiti = graphiti;
+
+  // Top-level config
+  if (env.REBAC_MEM_SUBJECT_TYPE) config.subjectType = env.REBAC_MEM_SUBJECT_TYPE;
+  if (env.REBAC_MEM_SUBJECT_ID) config.subjectId = env.REBAC_MEM_SUBJECT_ID;
+
+  return config;
+}
+
+function deepMerge(
+  base: Record<string, unknown>,
+  override: Record<string, unknown>,
+): Record<string, unknown> {
+  const result = { ...base };
+  for (const key of Object.keys(override)) {
+    if (
+      typeof result[key] === "object" && result[key] !== null && !Array.isArray(result[key]) &&
+      typeof override[key] === "object" && override[key] !== null && !Array.isArray(override[key])
+    ) {
+      result[key] = deepMerge(
+        result[key] as Record<string, unknown>,
+        override[key] as Record<string, unknown>,
+      );
+    } else {
+      result[key] = override[key];
+    }
+  }
+  return result;
+}
+
+// ============================================================================
+// Main
+// ============================================================================
+
+const program = new Command()
+  .name("rebac-mem")
+  .description("Standalone CLI for ReBAC memory management (Graphiti + SpiceDB)")
+  .option("--config <path>", "Path to config JSON file");
+
+const configIdx = process.argv.indexOf("--config");
+const configPath = configIdx !== -1 ? process.argv[configIdx + 1] : undefined;
+
+const fileConfig = loadConfigFile(configPath);
+const envConfig = loadConfigFromEnv();
+
+const mergedConfig = fileConfig ? deepMerge(fileConfig, envConfig) : envConfig;
+
+let cfg;
+try {
+  cfg = rebacMemoryConfigSchema.parse(mergedConfig);
+} catch (err) {
+  console.error(`Invalid configuration: ${err instanceof Error ? err.message : String(err)}`);
+  console.error("\nProvide config via environment variables or a JSON config file.");
+  console.error("Required: SPICEDB_TOKEN (or --config with spicedb.token)");
+  console.error("Optional: REBAC_MEM_BACKEND=graphiti (default: graphiti)");
+  process.exit(1);
+}
+
+const backend = createBackend(cfg);
+const spicedb = new SpiceDbClient(cfg.spicedb);
+const currentSubject = { type: cfg.subjectType, id: cfg.subjectId } as const;
+
+registerCommands(program, {
+  backend,
+  spicedb,
+  cfg,
+  currentSubject,
+  getLastWriteToken: () => undefined,
+});
+
+await program.parseAsync(process.argv);