@contextableai/openclaw-memory-rebac 0.1.0 → 0.1.2

package/dist/cli.js

@@ -0,0 +1,446 @@
+/**
+ * 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 { 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 { defaultGroupId } from "./config.js";
+import { lookupAuthorizedGroups, ensureGroupMembership, } from "./authorization.js";
+import { searchAuthorizedMemories } from "./search.js";
+// ============================================================================
+// Session helper (mirrors index.ts — no shared module to avoid circular import)
+// ============================================================================
+function sessionGroupId(sessionId) {
+    const sanitized = sessionId.replace(/[^a-zA-Z0-9_-]/g, "-");
+    return `session-${sanitized}`;
+}
+// ============================================================================
+// Command Registration
+// ============================================================================
+export function registerCommands(cmd, ctx) {
+    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, opts) => {
+        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, subjectId, opts) => {
+        const subjectType = opts.type === "agent" ? "agent" : "person";
+        await ensureGroupMembership(spicedb, groupId, {
+            type: subjectType,
+            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) => {
+        const workspacePath = resolve(opts.workspace);
+        const targetGroup = opts.group;
+        const importSessions = opts.includeSessions || opts.sessionsOnly;
+        const importWorkspace = !opts.sessionsOnly;
+        let mdFiles = [];
+        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;
+        }
+        const pending = [];
+        const membershipGroups = new Set();
+        // 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 = [];
+            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 = [];
+                    for (const line of lines) {
+                        try {
+                            const entry = JSON.parse(line);
+                            const msg = (entry.type === "message" && entry.message && typeof entry.message === "object")
+                                ? entry.message
+                                : entry;
+                            const role = msg.role;
+                            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) => typeof b === "object" && b !== null &&
+                                    b.type === "text" &&
+                                    typeof b.text === "string")
+                                    .map((b) => b.text)
+                                    .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 = [];
+        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.");
+    });
+    // --------------------------------------------------------------------------
+    // backfill-relationships — retroactively write per-fact SpiceDB relationships
+    // --------------------------------------------------------------------------
+    if (backend.discoverFragmentIds) {
+        cmd
+            .command("backfill-relationships")
+            .description("Retroactively write per-fact SpiceDB relationships for existing episodes")
+            .option("--group <id...>", "Group ID(s) to backfill (default: all authorized groups)")
+            .option("--last <n>", "Number of episodes per group to process", "100")
+            .option("--dry-run", "Show what would be written without writing", false)
+            .action(async (opts) => {
+            const lastN = parseInt(opts.last);
+            let groups;
+            if (opts.group && opts.group.length > 0) {
+                groups = opts.group;
+            }
+            else {
+                groups = await lookupAuthorizedGroups(spicedb, currentSubject, getLastWriteToken());
+                if (groups.length === 0) {
+                    console.log("No authorized groups found.");
+                    return;
+                }
+            }
+            console.log(`Backfilling per-fact SpiceDB relationships for ${groups.length} group(s)...`);
+            const tuples = [];
+            let totalEpisodes = 0;
+            let totalFacts = 0;
+            for (const groupId of groups) {
+                let episodes;
+                try {
+                    // getEpisodes is Graphiti-specific but we already checked discoverFragmentIds
+                    episodes = await backend.getEpisodes(groupId, lastN);
+                }
+                catch {
+                    console.log(`  Skipping group ${groupId} (failed to list episodes)`);
+                    continue;
+                }
+                console.log(`  Group "${groupId}": ${episodes.length} episode(s)`);
+                for (const ep of episodes) {
+                    const factIds = await backend.discoverFragmentIds(ep.uuid);
+                    if (factIds.length === 0)
+                        continue;
+                    totalEpisodes++;
+                    totalFacts += factIds.length;
+                    for (const factId of factIds) {
+                        tuples.push({
+                            resourceType: "memory_fragment",
+                            resourceId: factId,
+                            relation: "source_group",
+                            subjectType: "group",
+                            subjectId: groupId,
+                        }, {
+                            resourceType: "memory_fragment",
+                            resourceId: factId,
+                            relation: "shared_by",
+                            subjectType: currentSubject.type,
+                            subjectId: currentSubject.id,
+                        });
+                    }
+                    if (!opts.dryRun && factIds.length > 0) {
+                        process.stdout.write(".");
+                    }
+                }
+            }
+            if (!opts.dryRun && totalFacts > 0) {
+                console.log(); // newline after dots
+            }
+            console.log(`\nDiscovered ${totalFacts} fact(s) across ${totalEpisodes} episode(s).`);
+            if (opts.dryRun) {
+                console.log(`[dry-run] Would write ${tuples.length} SpiceDB relationships.`);
+                return;
+            }
+            if (tuples.length === 0) {
+                console.log("No relationships to write.");
+                return;
+            }
+            console.log(`Writing ${tuples.length} SpiceDB relationships...`);
+            try {
+                const count = await spicedb.bulkImportRelationships(tuples);
+                console.log(`Done: ${count} relationships written.`);
+            }
+            catch (err) {
+                console.error(`SpiceDB bulk import failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        });
+    }
+    // --------------------------------------------------------------------------
+    // Backend-specific extension point
+    // --------------------------------------------------------------------------
+    backend.registerCliCommands?.(cmd);
+}

package/dist/config.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 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";
+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;
+};
+export declare const rebacMemoryConfigSchema: {
+    parse(value: unknown): RebacMemoryConfig;
+};
+/**
+ * Instantiate the configured MemoryBackend from the parsed config.
+ * Call this once during plugin registration — the returned backend is stateful.
+ */
+export declare function createBackend(cfg: RebacMemoryConfig): MemoryBackend;
+/**
+ * Return the default group ID for the active backend.
+ */
+export declare function defaultGroupId(cfg: RebacMemoryConfig): string;

package/dist/config.js

@@ -0,0 +1,97 @@
+/**
+ * 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 { backendRegistry } from "./backends/registry.js";
+import pluginDefaults from "./plugin.defaults.json" with { type: "json" };
+// ============================================================================
+// Helpers
+// ============================================================================
+function resolveEnvVars(value) {
+    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, allowed, label) {
+    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) {
+        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 : {});
+        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 ?? {};
+        assertAllowedKeys(spicedb, ["endpoint", "token", "insecure"], "spicedb config");
+        // Backend config: user overrides merged over JSON defaults
+        const backendRaw = cfg[backendName] ?? {};
+        assertAllowedKeys(backendRaw, Object.keys(entry.defaults), `${backendName} config`);
+        const backendConfig = { ...entry.defaults, ...backendRaw };
+        const subjectType = cfg.subjectType === "person" ? "person" : pluginDefaults.subjectType;
+        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) {
+    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) {
+    return cfg.backendConfig["defaultGroupId"] ?? "main";
+}

package/dist/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * OpenClaw Memory (ReBAC) Plugin
+ *
+ * Two-layer memory architecture:
+ * - SpiceDB: authorization gateway (who can see what)
+ * - MemoryBackend: pluggable storage engine (Graphiti)
+ *
+ * SpiceDB determines which memories a subject can access.
+ * The backend stores the actual knowledge and handles search.
+ * Authorization is enforced at the data layer, not in prompts.
+ *
+ * Backend currently uses Graphiti for knowledge graph storage.
+ */
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+declare const rebacMemoryPlugin: {
+    id: string;
+    name: string;
+    description: string;
+    kind: "memory";
+    configSchema: {
+        parse(value: unknown): import("./config.js").RebacMemoryConfig;
+    };
+    register(api: OpenClawPluginApi): void;
+};
+export default rebacMemoryPlugin;