@contextableai/openclaw-memory-rebac 0.1.0

package/cli.ts

@@ -0,0 +1,418 @@
+/**
+ * Shared CLI command registration for rebac-mem.
+ *
+ * Registers backend-agnostic commands (search, status, schema-write, groups,
+ * add-member, import) then calls backend.registerCliCommands() for
+ * backend-specific extensions (e.g., graphiti: episodes, fact, clear-graph).
+ *
+ * Used by both the OpenClaw plugin (index.ts) and the standalone CLI
+ * (bin/rebac-mem.ts).
+ */
+
+import type { Command } from "commander";
+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 { fileURLToPath } from "node:url";
+
+import type { MemoryBackend } from "./backend.js";
+import type { SpiceDbClient, RelationshipTuple } from "./spicedb.js";
+import type { RebacMemoryConfig } from "./config.js";
+import { defaultGroupId } from "./config.js";
+import {
+  lookupAuthorizedGroups,
+  writeFragmentRelationships,
+  ensureGroupMembership,
+  type Subject,
+} from "./authorization.js";
+import { searchAuthorizedMemories } from "./search.js";
+
+// ============================================================================
+// Session helper (mirrors index.ts — no shared module to avoid circular import)
+// ============================================================================
+
+function sessionGroupId(sessionId: string): string {
+  const sanitized = sessionId.replace(/[^a-zA-Z0-9_-]/g, "-");
+  return `session-${sanitized}`;
+}
+
+// ============================================================================
+// CLI Context
+// ============================================================================
+
+export type CliContext = {
+  backend: MemoryBackend;
+  spicedb: SpiceDbClient;
+  cfg: RebacMemoryConfig;
+  currentSubject: Subject;
+  getLastWriteToken: () => string | undefined;
+};
+
+// ============================================================================
+// Command Registration
+// ============================================================================
+
+export function registerCommands(cmd: Command, ctx: CliContext): void {
+  const { backend, spicedb, cfg, currentSubject, getLastWriteToken } = ctx;
+  const defGroupId = defaultGroupId(cfg);
+
+  // --------------------------------------------------------------------------
+  // search
+  // --------------------------------------------------------------------------
+
+  cmd
+    .command("search")
+    .description("Search memories with authorization")
+    .argument("<query>", "Search query")
+    .option("--limit <n>", "Max results", "10")
+    .action(async (query: string, opts: { limit: string }) => {
+      const authorizedGroups = await lookupAuthorizedGroups(spicedb, currentSubject, getLastWriteToken());
+      if (authorizedGroups.length === 0) {
+        console.log("No accessible memory groups.");
+        return;
+      }
+      console.log(`Searching ${authorizedGroups.length} authorized groups...`);
+      const results = await searchAuthorizedMemories(backend, {
+        query,
+        groupIds: authorizedGroups,
+        limit: parseInt(opts.limit),
+      });
+      if (results.length === 0) {
+        console.log("No results found.");
+        return;
+      }
+      console.log(JSON.stringify(results, null, 2));
+    });
+
+  // --------------------------------------------------------------------------
+  // status
+  // --------------------------------------------------------------------------
+
+  cmd
+    .command("status")
+    .description("Check backend + SpiceDB health")
+    .action(async () => {
+      const backendStatus = await backend.getStatus();
+      let spicedbOk = false;
+      try {
+        await spicedb.readSchema();
+        spicedbOk = true;
+      } catch {
+        // unreachable
+      }
+      console.log(`Backend (${backend.name}): ${backendStatus.healthy ? "OK" : "UNREACHABLE"}`);
+      for (const [k, v] of Object.entries(backendStatus)) {
+        if (k !== "backend" && k !== "healthy") console.log(`  ${k}: ${v}`);
+      }
+      console.log(`SpiceDB: ${spicedbOk ? "OK" : "UNREACHABLE"} (${cfg.spicedb.endpoint})`);
+    });
+
+  // --------------------------------------------------------------------------
+  // schema-write
+  // --------------------------------------------------------------------------
+
+  cmd
+    .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.");
+    });
+
+  // --------------------------------------------------------------------------
+  // groups
+  // --------------------------------------------------------------------------
+
+  cmd
+    .command("groups")
+    .description("List authorized groups for current subject")
+    .action(async () => {
+      const groups = await lookupAuthorizedGroups(spicedb, currentSubject, getLastWriteToken());
+      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}`);
+    });
+
+  // --------------------------------------------------------------------------
+  // add-member
+  // --------------------------------------------------------------------------
+
+  cmd
+    .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}`);
+    });
+
+  // --------------------------------------------------------------------------
+  // import — ingest workspace files + session transcripts into the backend
+  // --------------------------------------------------------------------------
+
+  cmd
+    .command("import")
+    .description("Import workspace markdown files (and optionally session transcripts) into the backend")
+    .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", defGroupId)
+    .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;
+
+      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 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 — fine
+      }
+
+      if (importWorkspace) {
+        if (mdFiles.length === 0) {
+          console.log("No markdown files found in workspace.");
+        } else {
+          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;
+      }
+
+      // Phase 1: Store all content via backend.store(), collect fragmentId promises
+      type PendingResolution = {
+        fragmentId: Promise<string>;
+        groupId: string;
+        name: string;
+      };
+      const pending: PendingResolution[] = [];
+      const membershipGroups = new Set<string>();
+
+      // Phase 1a: Workspace files
+      if (importWorkspace && mdFiles.length > 0) {
+        if (importWorkspace) membershipGroups.add(targetGroup);
+        console.log(`\nPhase 1: Importing workspace files to ${backend.name} (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 backend.store({
+              content,
+              groupId: targetGroup,
+              sourceDescription: `Imported from workspace: ${f}`,
+            });
+            pending.push({ fragmentId: result.fragmentId, groupId: targetGroup, name: f });
+            console.log(`  Queued ${f} (${content.length} bytes)`);
+            imported++;
+          } catch (err) {
+            console.error(`  Failed to import ${f}: ${err instanceof Error ? err.message : String(err)}`);
+          }
+        }
+        console.log(`Workspace: ${imported}/${mdFiles.length} files ingested.`);
+      }
+
+      // Phase 1b: 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}`);
+        }
+
+        if (jsonlFiles.length === 0) {
+          console.log("\nNo session transcripts found.");
+        } else {
+          console.log(`\nPhase 1: Importing ${jsonlFiles.length} session transcript(s) to ${backend.name}...`);
+          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);
+
+            const conversationLines: string[] = [];
+            for (const line of lines) {
+              try {
+                const entry = JSON.parse(line) as Record<string, unknown>;
+                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 {
+              const result = await backend.store({
+                content: conversationLines.join("\n"),
+                groupId: sessionGroup,
+                sourceDescription: `Imported session transcript: ${sessionId}`,
+              });
+              membershipGroups.add(sessionGroup);
+              pending.push({ fragmentId: result.fragmentId, groupId: sessionGroup, name: f });
+              console.log(`  Queued ${f} (${conversationLines.length} messages) [group: ${sessionGroup}]`);
+              sessionsImported++;
+            } catch (err) {
+              console.error(`  Failed to import ${f}: ${err instanceof Error ? err.message : String(err)}`);
+            }
+          }
+          console.log(`Sessions: ${sessionsImported}/${jsonlFiles.length} transcripts ingested.`);
+        }
+      }
+
+      // Phase 1.5: Await all fragmentIds concurrently
+      const pendingTuples: RelationshipTuple[] = [];
+      if (pending.length > 0) {
+        console.log(`\nResolving ${pending.length} fragment UUIDs...`);
+        const resolutions = await Promise.allSettled(pending.map((p) => p.fragmentId));
+        for (let i = 0; i < resolutions.length; i++) {
+          const r = resolutions[i];
+          if (r.status === "fulfilled") {
+            const fragmentId = r.value;
+            pendingTuples.push(
+              {
+                resourceType: "memory_fragment",
+                resourceId: fragmentId,
+                relation: "source_group",
+                subjectType: "group",
+                subjectId: pending[i].groupId,
+              },
+              {
+                resourceType: "memory_fragment",
+                resourceId: fragmentId,
+                relation: "shared_by",
+                subjectType: currentSubject.type,
+                subjectId: currentSubject.id,
+              },
+            );
+            console.log(`  ${pending[i].name} → ${fragmentId}`);
+          } else {
+            console.warn(`  Warning: could not resolve UUID for ${pending[i].name} — SpiceDB linkage skipped`);
+          }
+        }
+      }
+
+      // Phase 2: Bulk write SpiceDB relationships + memberships
+      if (pendingTuples.length > 0 || membershipGroups.size > 0) {
+        for (const groupId of membershipGroups) {
+          pendingTuples.push({
+            resourceType: "group",
+            resourceId: groupId,
+            relation: "member",
+            subjectType: currentSubject.type,
+            subjectId: currentSubject.id,
+          });
+        }
+
+        console.log(`\nPhase 2: Writing ${pendingTuples.length} SpiceDB relationships...`);
+        try {
+          const count = await spicedb.bulkImportRelationships(pendingTuples);
+          console.log(`SpiceDB: ${count} relationships written.`);
+        } catch (err) {
+          console.error(`SpiceDB bulk import failed: ${err instanceof Error ? err.message : String(err)}`);
+          console.error("Backend episodes were ingested but lack authorization. Re-run import or add relationships manually.");
+        }
+      }
+
+      console.log("\nImport complete.");
+    });
+
+  // --------------------------------------------------------------------------
+  // Backend-specific extension point
+  // --------------------------------------------------------------------------
+
+  backend.registerCliCommands?.(cmd);
+}

package/config.ts

@@ -0,0 +1,141 @@
+/**
+ * Unified configuration for openclaw-memory-rebac.
+ *
+ * Backend-specific defaults live in backends/<name>.defaults.json.
+ * Available backends are listed in backends/backends.json.
+ * No backend names appear in this file.
+ */
+
+import type { MemoryBackend } from "./backend.js";
+import { backendRegistry } from "./backends/registry.js";
+import pluginDefaults from "./plugin.defaults.json" with { type: "json" };
+
+// ============================================================================
+// Config type
+// ============================================================================
+
+export type RebacMemoryConfig = {
+  backend: string;
+  spicedb: {
+    endpoint: string;
+    token: string;
+    insecure: boolean;
+  };
+  backendConfig: Record<string, unknown>;
+  subjectType: "agent" | "person";
+  subjectId: string;
+  autoCapture: boolean;
+  autoRecall: boolean;
+  maxCaptureMessages: number;
+};
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+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(", ")}`);
+  }
+}
+
+// ============================================================================
+// Config schema
+// ============================================================================
+
+export const rebacMemoryConfigSchema = {
+  parse(value: unknown): RebacMemoryConfig {
+    if (Array.isArray(value)) {
+      throw new Error("openclaw-memory-rebac config must be an object, not an array");
+    }
+    const cfg = (value && typeof value === "object" ? value : {}) as Record<string, unknown>;
+
+    const backendName =
+      typeof cfg.backend === "string" ? cfg.backend : pluginDefaults.backend;
+
+    const entry = backendRegistry[backendName];
+    if (!entry) throw new Error(`Unknown backend: "${backendName}"`);
+
+    // Top-level allowed keys: shared keys + the backend name key
+    assertAllowedKeys(
+      cfg,
+      [
+        "backend", "spicedb",
+        "subjectType", "subjectId",
+        "autoCapture", "autoRecall", "maxCaptureMessages",
+        backendName,
+      ],
+      "openclaw-memory-rebac config",
+    );
+
+    // SpiceDB config (shared)
+    const spicedb = (cfg.spicedb as Record<string, unknown>) ?? {};
+    assertAllowedKeys(spicedb, ["endpoint", "token", "insecure"], "spicedb config");
+
+    // Backend config: user overrides merged over JSON defaults
+    const backendRaw = (cfg[backendName] as Record<string, unknown>) ?? {};
+    assertAllowedKeys(backendRaw, Object.keys(entry.defaults), `${backendName} config`);
+    const backendConfig = { ...entry.defaults, ...backendRaw };
+
+    const subjectType =
+      cfg.subjectType === "person" ? "person" : (pluginDefaults.subjectType as "agent" | "person");
+    const subjectId =
+      typeof cfg.subjectId === "string" ? resolveEnvVars(cfg.subjectId) : pluginDefaults.subjectId;
+
+    return {
+      backend: backendName,
+      spicedb: {
+        endpoint:
+          typeof spicedb.endpoint === "string"
+            ? spicedb.endpoint
+            : pluginDefaults.spicedb.endpoint,
+        token: typeof spicedb.token === "string" ? resolveEnvVars(spicedb.token) : "",
+        insecure:
+          typeof spicedb.insecure === "boolean"
+            ? spicedb.insecure
+            : pluginDefaults.spicedb.insecure,
+      },
+      backendConfig,
+      subjectType,
+      subjectId,
+      autoCapture: cfg.autoCapture !== false,
+      autoRecall: cfg.autoRecall !== false,
+      maxCaptureMessages:
+        typeof cfg.maxCaptureMessages === "number" && cfg.maxCaptureMessages > 0
+          ? cfg.maxCaptureMessages
+          : pluginDefaults.maxCaptureMessages,
+    };
+  },
+};
+
+// ============================================================================
+// Backend factory
+// ============================================================================
+
+/**
+ * Instantiate the configured MemoryBackend from the parsed config.
+ * Call this once during plugin registration — the returned backend is stateful.
+ */
+export function createBackend(cfg: RebacMemoryConfig): MemoryBackend {
+  const entry = backendRegistry[cfg.backend];
+  if (!entry) throw new Error(`Unknown backend: "${cfg.backend}"`);
+  return entry.create(cfg.backendConfig);
+}
+
+/**
+ * Return the default group ID for the active backend.
+ */
+export function defaultGroupId(cfg: RebacMemoryConfig): string {
+  return (cfg.backendConfig["defaultGroupId"] as string) ?? "main";
+}

package/docker/docker-compose.yml

@@ -0,0 +1,17 @@
+###############################################################################
+# openclaw-memory-rebac — Combined stack (Graphiti + SpiceDB)
+#
+# Brings up the full memory service stack in a single command:
+#   - Graphiti FastAPI REST server + Neo4j
+#   - SpiceDB authorization engine + PostgreSQL
+#
+# Usage:
+#   docker compose up -d
+#
+# Graphiti endpoint:  http://localhost:8000
+# SpiceDB endpoint:   localhost:50051 (insecure)
+###############################################################################
+
+include:
+  - path: ./spicedb/docker-compose.yml
+  - path: ./graphiti/docker-compose.yml

package/docker/graphiti/Dockerfile

@@ -0,0 +1,35 @@
+###############################################################################
+# Custom Graphiti FastAPI server with per-component LLM/embedder/reranker
+# configurability and BGE reranker support.
+#
+# Extends the base zepai/graphiti image to:
+#   1. Install sentence-transformers for BGE reranker
+#   2. Overlay per-component config + startup to wire separate clients
+###############################################################################
+
+FROM zepai/graphiti:latest
+
+# Base image runs as non-root "app" user; switch to root to install packages
+USER root
+
+# Ensure the venv is active for all subsequent RUN and CMD
+ENV VIRTUAL_ENV=/app/.venv
+ENV PATH="/app/.venv/bin:${PATH}"
+
+# Install sentence-transformers for BGE reranker (runs locally, no API needed)
+RUN uv pip install 'sentence-transformers>=3.2.1' \
+    && python -c "import sentence_transformers; print('OK')"
+
+# Overlay: per-component config + startup
+COPY config_overlay.py /app/graph_service/config_overlay.py
+COPY graphiti_overlay.py /app/graph_service/graphiti_overlay.py
+COPY startup.py /app/startup.py
+
+# Fix ownership for app user
+RUN chown -R app:app /app
+
+# Switch back to non-root user
+USER app
+
+# Run startup directly via venv python (not `uv run`, which may reset the venv)
+CMD ["/app/.venv/bin/python", "/app/startup.py"]

package/docker/graphiti/config_overlay.py

@@ -0,0 +1,44 @@
+"""
+Extended Graphiti Settings with per-component embedder/reranker configuration.
+
+Adds these env vars beyond the base Settings:
+  EMBEDDING_BASE_URL  — separate base URL for embedder (defaults to OPENAI_BASE_URL)
+  EMBEDDING_API_KEY   — separate API key for embedder (defaults to OPENAI_API_KEY)
+  EMBEDDING_DIM       — embedding dimensions (default: unset, uses model default)
+  RERANKER_PROVIDER   — "bge" (local, default) or "openai" (remote API)
+  RERANKER_MODEL      — model name for remote reranker (ignored when provider=bge)
+  RERANKER_BASE_URL   — base URL for remote reranker (ignored when provider=bge)
+  RERANKER_API_KEY    — API key for remote reranker (ignored when provider=bge)
+"""
+
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class ExtendedSettings(BaseSettings):
+    # -- LLM (entity extraction) --
+    openai_api_key: str
+    openai_base_url: str | None = Field(None)
+    model_name: str | None = Field(None)
+
+    # -- Embedder --
+    embedding_model_name: str | None = Field(None)
+    embedding_base_url: str | None = Field(None)
+    embedding_api_key: str | None = Field(None)
+    embedding_dim: int | None = Field(None)
+
+    # -- Reranker / cross-encoder --
+    reranker_provider: str = "bge"  # "bge" (local) or "openai" (remote)
+    reranker_model: str | None = Field(None)
+    reranker_base_url: str | None = Field(None)
+    reranker_api_key: str | None = Field(None)
+
+    # -- Neo4j --
+    neo4j_uri: str = "bolt://localhost:7687"
+    neo4j_user: str = "neo4j"
+    neo4j_password: str = "password"
+
+    # -- Server --
+    port: int = 8000
+
+    model_config = SettingsConfigDict(env_file=".env", extra="ignore")