@contextableai/openclaw-memory-rebac 0.1.0

package/openclaw.plugin.json

@@ -0,0 +1,118 @@
+{
+  "id": "openclaw-memory-rebac",
+  "kind": "memory",
+  "uiHints": {
+    "backend": {
+      "label": "Memory Backend",
+      "placeholder": "graphiti",
+      "help": "Storage engine: 'graphiti' (REST knowledge graph)"
+    },
+    "spicedb.endpoint": {
+      "label": "SpiceDB Endpoint",
+      "placeholder": "localhost:50051",
+      "help": "SpiceDB gRPC endpoint (host:port)"
+    },
+    "spicedb.token": {
+      "label": "SpiceDB Token",
+      "sensitive": true,
+      "placeholder": "dev_token",
+      "help": "SpiceDB pre-shared key (or use ${SPICEDB_TOKEN})"
+    },
+    "spicedb.insecure": {
+      "label": "Insecure Connection",
+      "help": "Allow insecure gRPC to localhost (dev mode)"
+    },
+    "graphiti.endpoint": {
+      "label": "Graphiti Endpoint",
+      "placeholder": "http://localhost:8000",
+      "help": "Graphiti REST server HTTP base URL"
+    },
+    "graphiti.defaultGroupId": {
+      "label": "Graphiti Default Group ID",
+      "placeholder": "main",
+      "help": "Default Graphiti group_id for memory isolation"
+    },
+    "graphiti.uuidPollIntervalMs": {
+      "label": "UUID Poll Interval (ms)",
+      "placeholder": "3000",
+      "help": "Polling interval for resolving episode UUIDs after store (default: 3000)",
+      "advanced": true
+    },
+    "graphiti.uuidPollMaxAttempts": {
+      "label": "UUID Poll Max Attempts",
+      "placeholder": "30",
+      "help": "Max polling attempts; total timeout = interval × attempts (default: 30 = 90s)",
+      "advanced": true
+    },
+    "graphiti.requestTimeoutMs": {
+      "label": "Request Timeout (ms)",
+      "placeholder": "30000",
+      "help": "HTTP request timeout for Graphiti REST calls (default: 30000)",
+      "advanced": true
+    },
+    "subjectType": {
+      "label": "Subject Type",
+      "placeholder": "agent",
+      "help": "SpiceDB subject object type (agent or person)",
+      "advanced": true
+    },
+    "subjectId": {
+      "label": "Subject ID",
+      "placeholder": "${OPENCLAW_AGENT_ID}",
+      "help": "SpiceDB subject ID for the current agent/person"
+    },
+    "autoCapture": {
+      "label": "Auto-Capture",
+      "help": "Automatically capture important information from conversations"
+    },
+    "autoRecall": {
+      "label": "Auto-Recall",
+      "help": "Automatically inject relevant memories into context"
+    },
+    "customInstructions": {
+      "label": "Custom Extraction Instructions",
+      "help": "Natural language rules for what the backend should extract from conversations",
+      "advanced": true
+    },
+    "maxCaptureMessages": {
+      "label": "Max Capture Messages",
+      "help": "Maximum number of recent messages to include in auto-capture (default: 10)",
+      "advanced": true
+    }
+  },
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": true,
+    "properties": {
+      "backend": {
+        "type": "string"
+      },
+      "spicedb": {
+        "type": "object",
+        "additionalProperties": true,
+        "properties": {
+          "endpoint": { "type": "string" },
+          "token": { "type": "string" },
+          "insecure": { "type": "boolean" }
+        }
+      },
+      "graphiti": {
+        "type": "object",
+        "additionalProperties": true,
+        "properties": {
+          "endpoint": { "type": "string" },
+          "defaultGroupId": { "type": "string" },
+          "uuidPollIntervalMs": { "type": "integer", "minimum": 500, "maximum": 30000 },
+          "uuidPollMaxAttempts": { "type": "integer", "minimum": 1, "maximum": 200 },
+          "requestTimeoutMs": { "type": "integer", "minimum": 1000, "maximum": 300000 }
+        }
+      },
+      "subjectType": { "type": "string", "enum": ["agent", "person"] },
+      "subjectId": { "type": "string" },
+      "autoCapture": { "type": "boolean" },
+      "autoRecall": { "type": "boolean" },
+      "customInstructions": { "type": "string" },
+      "maxCaptureMessages": { "type": "integer", "minimum": 1, "maximum": 50 }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@contextableai/openclaw-memory-rebac",
+  "version": "0.1.0",
+  "description": "OpenClaw two-layer memory plugin: SpiceDB ReBAC authorization + Graphiti knowledge graph",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Contextable/openclaw-memory-rebac.git"
+  },
+  "keywords": [
+    "openclaw",
+    "memory",
+    "graphiti",
+    "spicedb",
+    "rebac",
+    "knowledge-graph",
+    "authorization"
+  ],
+  "files": [
+    "index.ts",
+    "cli.ts",
+    "config.ts",
+    "backend.ts",
+    "authorization.ts",
+    "search.ts",
+    "spicedb.ts",
+    "backends/",
+    "openclaw.plugin.json",
+    "plugin.defaults.json",
+    "schema.zed",
+    "docker/",
+    "scripts/",
+    "bin/"
+  ],
+  "peerDependencies": {
+    "openclaw": "*"
+  },
+  "scripts": {
+    "cli": "tsx bin/rebac-mem.ts",
+    "typecheck": "tsc --noEmit 2>&1 | grep -v '../openclaw/' | grep -c 'error TS' | xargs -I{} test {} -eq 0",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:e2e": "OPENCLAW_LIVE_TEST=1 vitest run --config vitest.e2e.config.ts"
+  },
+  "dependencies": {
+    "@authzed/authzed-node": "^1.2.0",
+    "@grpc/grpc-js": "^1.14.3",
+    "@sinclair/typebox": "0.34.48",
+    "commander": "^13.1.0"
+  },
+  "devDependencies": {
+    "dotenv": "^17.3.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "install": {
+      "npmSpec": "@contextableai/openclaw-memory-rebac",
+      "localPath": "extensions/openclaw-memory-rebac",
+      "defaultChoice": "npm"
+    }
+  }
+}

package/plugin.defaults.json

@@ -0,0 +1,12 @@
+{
+  "backend": "graphiti",
+  "spicedb": {
+    "endpoint": "localhost:50051",
+    "insecure": true
+  },
+  "subjectType": "agent",
+  "subjectId": "default",
+  "autoCapture": true,
+  "autoRecall": true,
+  "maxCaptureMessages": 10
+}

package/schema.zed

@@ -0,0 +1,23 @@
+definition person {}
+
+definition agent {
+    relation owner: person
+    permission act_as = owner
+}
+
+definition group {
+    relation member: person | agent
+    permission access = member
+    permission contribute = member
+}
+
+definition memory_fragment {
+    relation source_group: group
+    relation involves: person | agent
+    relation shared_by: person | agent
+
+    // Can view if: directly involved, shared it, or have access to the source group
+    permission view = involves + shared_by + source_group->access
+    // Can delete if: you shared it (owner-level control)
+    permission delete = shared_by
+}

package/search.ts

@@ -0,0 +1,139 @@
+/**
+ * Parallel Multi-Group Search + Merge/Re-rank
+ *
+ * Backend-agnostic: delegates per-group search to MemoryBackend.searchGroup().
+ * Issues parallel calls (one per authorized group_id), merges results,
+ * deduplicates by UUID, and re-ranks by score then recency.
+ */
+
+import type { MemoryBackend, SearchResult } from "./backend.js";
+
+export type { SearchResult };
+
+// ============================================================================
+// Search options
+// ============================================================================
+
+export type SearchOptions = {
+  query: string;
+  groupIds: string[];
+  limit?: number;
+  sessionId?: string;
+};
+
+// ============================================================================
+// Search
+// ============================================================================
+
+/**
+ * Search across multiple authorized group_ids in parallel.
+ * Merges and deduplicates results, returning up to `limit` items sorted by
+ * score (desc) then recency (desc).
+ */
+export async function searchAuthorizedMemories(
+  backend: MemoryBackend,
+  options: SearchOptions,
+): Promise<SearchResult[]> {
+  const { query, groupIds, limit = 10, sessionId } = options;
+
+  if (groupIds.length === 0) {
+    return [];
+  }
+
+  // Fan out parallel searches across all authorized groups
+  const promises = groupIds.map((groupId) =>
+    backend.searchGroup({ query, groupId, limit, sessionId }),
+  );
+
+  const resultSets = await Promise.allSettled(promises);
+
+  // Collect all successful results — silently skip failed group searches
+  const allResults: SearchResult[] = [];
+  for (const result of resultSets) {
+    if (result.status === "fulfilled") {
+      allResults.push(...result.value);
+    }
+  }
+
+  // Deduplicate by UUID
+  const seen = new Set<string>();
+  const deduped = allResults.filter((r) => {
+    if (seen.has(r.uuid)) return false;
+    seen.add(r.uuid);
+    return true;
+  });
+
+  // Sort: score descending (when available), then recency descending
+  deduped.sort((a, b) => {
+    if (a.score !== undefined && b.score !== undefined && a.score !== b.score) {
+      return b.score - a.score;
+    }
+    const dateA = new Date(a.created_at).getTime();
+    const dateB = new Date(b.created_at).getTime();
+    return dateB - dateA;
+  });
+
+  return deduped.slice(0, limit);
+}
+
+// ============================================================================
+// Format for agent context
+// ============================================================================
+
+/**
+ * Format search results into a text block for injecting into agent context.
+ */
+export function formatResultsForContext(results: SearchResult[]): string {
+  if (results.length === 0) return "";
+  return results.map((r, i) => formatResultLine(r, i + 1)).join("\n");
+}
+
+/**
+ * Format results with long-term and session sections separated.
+ * Session group_ids start with "session-".
+ */
+export function formatDualResults(
+  longTermResults: SearchResult[],
+  sessionResults: SearchResult[],
+): string {
+  const parts: string[] = [];
+  let idx = 1;
+
+  for (const r of longTermResults) {
+    parts.push(formatResultLine(r, idx++));
+  }
+
+  if (sessionResults.length > 0) {
+    if (longTermResults.length > 0) parts.push("Session memories:");
+    for (const r of sessionResults) {
+      parts.push(formatResultLine(r, idx++));
+    }
+  }
+
+  return parts.join("\n");
+}
+
+/**
+ * Format a single search result line with type-prefixed UUID.
+ * e.g. "[fact:da8650cb-...] Eric's birthday is Dec 17th (Eric -[HAS_BIRTHDAY]→ Dec 17th)"
+ */
+function formatResultLine(r: SearchResult, idx: number): string {
+  const typeLabel =
+    r.type === "node" ? "entity" :
+    r.type === "fact" ? "fact" :
+    r.type === "chunk" ? "chunk" :
+    r.type === "summary" ? "summary" :
+    "completion";
+  return `${idx}. [${typeLabel}:${r.uuid}] ${r.summary} (${r.context})`;
+}
+
+/**
+ * Deduplicate session results against long-term results (by UUID).
+ */
+export function deduplicateSessionResults(
+  longTermResults: SearchResult[],
+  sessionResults: SearchResult[],
+): SearchResult[] {
+  const longTermIds = new Set(longTermResults.map((r) => r.uuid));
+  return sessionResults.filter((r) => !longTermIds.has(r.uuid));
+}