@contextableai/openclaw-memory-rebac 0.3.0 → 0.3.1

package/README.md

@@ -213,6 +213,41 @@ Session groups (`session-<id>`) provide per-conversation memory isolation:
 - Other agents cannot read or write to foreign session groups without explicit membership
 - Session memories are searchable within the session scope and are deduplicated against long-term memories
 
+### Per-Agent Identity
+
+When multiple agents share a single OpenClaw gateway, each agent gets its own SpiceDB identity. Tools and lifecycle hooks derive the subject from the runtime `agentId` — so `agent:stenographer` and `agent:main` write memories with distinct `shared_by` relationships, even though they run through the same plugin instance.
+
+If `agentId` is not available in the runtime context (e.g., older OpenClaw versions or standalone CLI use), the plugin falls back to the config-level `subjectType`/`subjectId`.
+
+Session state (session IDs and SpiceDB consistency tokens) is also tracked per agent, so agents don't interfere with each other's sessions.
+
+### Identity Linking
+
+The `identities` config field connects agents to the people they represent. This is essential for **cross-agent recall** — finding memories stored by one agent that involve a person represented by a different agent.
+
+```json
+{
+  "identities": {
+    "main": "U0123ABC",
+    "work": "U0456DEF"
+  }
+}
+```
+
+Each entry maps an agent ID to a person ID (typically a Slack user ID or other external identifier). At plugin startup, the plugin writes `agent:<agentId> #owner person:<personId>` relationships to SpiceDB.
+
+**How cross-agent recall works:**
+
+1. Agent A stores a memory with `involves: ["U0123ABC"]`
+2. Later, agent B (configured as `"main": "U0123ABC"`) calls `memory_recall`
+3. The plugin resolves `agent:main` → `person:U0123ABC` via SpiceDB
+4. It discovers the memory because `person:U0123ABC` is in `involves`
+5. The memory is returned alongside group-based results
+
+This means a user's personal agent can discover memories stored by service agents (like a meeting recorder or Slack observer), as long as the user was a participant. The service agent retains `shared_by` ownership (and exclusive delete permission), while involved people get view access through their own agents.
+
+Agents without an `identities` entry (like service agents) are not linked to any person and cannot be resolved through identity chains. This is intentional — a service agent acts on its own behalf, not on behalf of a human.
+
 ## Configuration Reference
 
 | Key | Type | Default | Description |
@@ -227,7 +262,8 @@ Session groups (`session-<id>`) provide per-conversation memory isolation:
 | `graphiti.uuidPollMaxAttempts` | integer | `60` | Max polling attempts (total timeout = interval x attempts) |
 | `graphiti.requestTimeoutMs` | integer | `30000` | HTTP request timeout for Graphiti REST calls (ms) |
 | `subjectType` | string | `agent` | SpiceDB subject type (`agent` or `person`) |
-| `subjectId` | string | `default` | SpiceDB subject ID (supports `${ENV_VAR}`) |
+| `subjectId` | string | `default` | Fallback SpiceDB subject ID when agentId is unavailable (supports `${ENV_VAR}`) |
+| `identities` | object | `{}` | Maps agent IDs to owner person IDs for cross-agent recall (see [Identity Linking](#identity-linking)) |
 | `autoCapture` | boolean | `true` | Auto-capture conversations |
 | `autoRecall` | boolean | `true` | Auto-inject relevant memories |
 | `customInstructions` | string | *(see below)* | Custom extraction instructions |
@@ -267,13 +303,18 @@ All commands are under `rebac-mem`:
 
 | Command | Description |
 |---------|-------------|
-| `rebac-mem search <query>` | Search memories with authorization. Options: `--limit`, `--scope` |
-| `rebac-mem status` | Check SpiceDB + backend connectivity |
+| `rebac-mem search <query>` | Search memories with authorization (includes owner-aware recall). Options: `--limit`, `--as` |
+| `rebac-mem status` | Check SpiceDB + backend connectivity, show subject and identity links |
 | `rebac-mem schema-write` | Write/update the SpiceDB authorization schema |
-| `rebac-mem groups` | List authorized groups for the current subject |
+| `rebac-mem groups` | List authorized groups for a subject. Options: `--as` |
 | `rebac-mem add-member <group-id> <subject-id>` | Add a subject to a group. Options: `--type` |
+| `rebac-mem identities` | List configured identity links and verify them in SpiceDB |
+| `rebac-mem link-identity <agent-id> <person-id>` | Write an agent→owner relationship to SpiceDB |
+| `rebac-mem unlink-identity <agent-id>` | Remove an agent→owner relationship from SpiceDB |
 | `rebac-mem import` | Import workspace markdown files. Options: `--workspace`, `--include-sessions`, `--group`, `--dry-run` |
 
+The `--as` flag accepts `"type:id"` (e.g., `"agent:main"`, `"person:U0123ABC"`) or a bare `"id"` (defaults to agent type). Use it to query as a different subject without changing config.
+
 Backend-specific commands (Graphiti):
 
 | Command | Description |
@@ -340,6 +381,9 @@ OpenClaw has an exclusive `memory` slot — only one memory plugin is active at
           },
           "subjectType": "agent",
           "subjectId": "my-agent",
+          "identities": {
+            "my-agent": "U0123ABC"
+          },
           "autoCapture": true,
           "autoRecall": true
         }

package/dist/cli.d.ts

@@ -13,6 +13,11 @@ import type { MemoryBackend } from "./backend.js";
 import type { SpiceDbClient } from "./spicedb.js";
 import type { RebacMemoryConfig } from "./config.js";
 import { type Subject } from "./authorization.js";
+/**
+ * Parse an --as flag value into a Subject.
+ * Accepts "type:id" (e.g., "agent:main", "person:U0123ABC") or bare "id" (defaults to agent type).
+ */
+export declare function parseSubjectOverride(value: string): Subject;
 export type CliContext = {
     backend: MemoryBackend;
     spicedb: SpiceDbClient;

package/dist/cli.js

@@ -14,7 +14,7 @@ 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 { lookupAuthorizedGroups, lookupAgentOwner, lookupViewableFragments, ensureGroupMembership, } from "./authorization.js";
 import { searchAuthorizedMemories } from "./search.js";
 // ============================================================================
 // Session helper (mirrors index.ts — no shared module to avoid circular import)
@@ -24,6 +24,25 @@ function sessionGroupId(sessionId) {
     return `session-${sanitized}`;
 }
 // ============================================================================
+// Subject parsing helper
+// ============================================================================
+/**
+ * Parse an --as flag value into a Subject.
+ * Accepts "type:id" (e.g., "agent:main", "person:U0123ABC") or bare "id" (defaults to agent type).
+ */
+export function parseSubjectOverride(value) {
+    const colonIdx = value.indexOf(":");
+    if (colonIdx !== -1) {
+        const type = value.slice(0, colonIdx);
+        const id = value.slice(colonIdx + 1);
+        if (type !== "agent" && type !== "person") {
+            throw new Error(`Invalid subject type "${type}" — must be "agent" or "person"`);
+        }
+        return { type, id };
+    }
+    return { type: "agent", id: value };
+}
+// ============================================================================
 // Command Registration
 // ============================================================================
 export function registerCommands(cmd, ctx) {
@@ -34,26 +53,54 @@ export function registerCommands(cmd, ctx) {
     // --------------------------------------------------------------------------
     cmd
         .command("search")
-        .description("Search memories with authorization")
+        .description("Search memories with authorization (includes owner-aware recall for agents)")
         .argument("<query>", "Search query")
         .option("--limit <n>", "Max results", "10")
+        .option("--as <subject>", "Override subject (e.g., \"main\", \"agent:main\", \"person:U0123ABC\")")
         .action(async (query, opts) => {
-        const authorizedGroups = await lookupAuthorizedGroups(spicedb, currentSubject, getLastWriteToken());
-        if (authorizedGroups.length === 0) {
-            console.log("No accessible memory groups.");
-            return;
+        const subject = opts.as ? parseSubjectOverride(opts.as) : currentSubject;
+        const token = getLastWriteToken();
+        // Group-based search
+        const authorizedGroups = await lookupAuthorizedGroups(spicedb, subject, token);
+        console.log(`Searching as ${subject.type}:${subject.id}...`);
+        const groupResults = authorizedGroups.length > 0
+            ? await searchAuthorizedMemories(backend, {
+                query,
+                groupIds: authorizedGroups,
+                limit: parseInt(opts.limit),
+            })
+            : [];
+        // Owner-aware recall: if agent, resolve owner and find involves fragments
+        let ownerResults = [];
+        if (subject.type === "agent" && backend.getFragmentsByIds) {
+            try {
+                const ownerId = await lookupAgentOwner(spicedb, subject.id, token);
+                if (ownerId) {
+                    const ownerSubject = { type: "person", id: ownerId };
+                    const viewableIds = await lookupViewableFragments(spicedb, ownerSubject, token);
+                    if (viewableIds.length > 0) {
+                        const groupResultIds = new Set(groupResults.map((r) => r.uuid));
+                        const newIds = viewableIds.filter((id) => !groupResultIds.has(id));
+                        if (newIds.length > 0) {
+                            ownerResults = await backend.getFragmentsByIds(newIds);
+                        }
+                    }
+                    if (ownerResults.length > 0) {
+                        console.log(`  + ${ownerResults.length} result(s) via owner identity (person:${ownerId})`);
+                    }
+                }
+            }
+            catch {
+                // Owner lookup failed — proceed with group results only
+            }
         }
-        console.log(`Searching ${authorizedGroups.length} authorized groups...`);
-        const results = await searchAuthorizedMemories(backend, {
-            query,
-            groupIds: authorizedGroups,
-            limit: parseInt(opts.limit),
-        });
-        if (results.length === 0) {
+        const allResults = [...groupResults, ...ownerResults];
+        if (allResults.length === 0) {
             console.log("No results found.");
             return;
         }
-        console.log(JSON.stringify(results, null, 2));
+        console.log(`Found ${allResults.length} result(s) across ${authorizedGroups.length} group(s).`);
+        console.log(JSON.stringify(allResults, null, 2));
     });
     // --------------------------------------------------------------------------
     // status
@@ -77,6 +124,14 @@ export function registerCommands(cmd, ctx) {
                 console.log(`  ${k}: ${v}`);
         }
         console.log(`SpiceDB: ${spicedbOk ? "OK" : "UNREACHABLE"} (${cfg.spicedb.endpoint})`);
+        console.log(`Subject: ${currentSubject.type}:${currentSubject.id}`);
+        const identityEntries = Object.entries(cfg.identities);
+        if (identityEntries.length > 0) {
+            console.log(`Identities: ${identityEntries.length} configured`);
+            for (const [agentId, personId] of identityEntries) {
+                console.log(`  agent:${agentId} → person:${personId}`);
+            }
+        }
     });
     // --------------------------------------------------------------------------
     // schema-write
@@ -95,14 +150,16 @@ export function registerCommands(cmd, ctx) {
     // --------------------------------------------------------------------------
     cmd
         .command("groups")
-        .description("List authorized groups for current subject")
-        .action(async () => {
-        const groups = await lookupAuthorizedGroups(spicedb, currentSubject, getLastWriteToken());
+        .description("List authorized groups for a subject")
+        .option("--as <subject>", "Override subject (e.g., \"main\", \"agent:stenographer\")")
+        .action(async (opts) => {
+        const subject = opts.as ? parseSubjectOverride(opts.as) : currentSubject;
+        const groups = await lookupAuthorizedGroups(spicedb, subject, getLastWriteToken());
         if (groups.length === 0) {
-            console.log("No authorized groups.");
+            console.log(`No authorized groups for ${subject.type}:${subject.id}.`);
             return;
         }
-        console.log(`Authorized groups for ${currentSubject.type}:${currentSubject.id}:`);
+        console.log(`Authorized groups for ${subject.type}:${subject.id}:`);
         for (const g of groups)
             console.log(`  - ${g}`);
     });
@@ -449,6 +506,93 @@ export function registerCommands(cmd, ctx) {
         });
     }
     // --------------------------------------------------------------------------
+    // identities — list and verify agent→owner identity links
+    // --------------------------------------------------------------------------
+    cmd
+        .command("identities")
+        .description("List configured identity links and verify them in SpiceDB")
+        .action(async () => {
+        const identities = cfg.identities;
+        const entries = Object.entries(identities);
+        if (entries.length === 0) {
+            console.log("No identities configured.");
+            console.log("Add an \"identities\" field to your config to link agents to their owners:");
+            console.log('  { "identities": { "main": "U0123ABC" } }');
+            return;
+        }
+        console.log("Configured identity links:\n");
+        for (const [agentId, personId] of entries) {
+            let spicedbStatus;
+            try {
+                const ownerId = await lookupAgentOwner(spicedb, agentId, getLastWriteToken());
+                if (ownerId === personId) {
+                    spicedbStatus = "verified";
+                }
+                else if (ownerId) {
+                    spicedbStatus = `mismatch (SpiceDB has person:${ownerId})`;
+                }
+                else {
+                    spicedbStatus = "not found in SpiceDB";
+                }
+            }
+            catch {
+                spicedbStatus = "SpiceDB unreachable";
+            }
+            console.log(`  agent:${agentId} → person:${personId}  [${spicedbStatus}]`);
+        }
+        console.log("\nTo write missing links, restart the gateway or use: rebac-mem link-identity <agent-id> <person-id>");
+    });
+    // --------------------------------------------------------------------------
+    // link-identity — write an agent→owner relationship to SpiceDB
+    // --------------------------------------------------------------------------
+    cmd
+        .command("link-identity")
+        .description("Write an agent→owner relationship to SpiceDB")
+        .argument("<agent-id>", "Agent ID")
+        .argument("<person-id>", "Owner person ID")
+        .action(async (agentId, personId) => {
+        try {
+            await spicedb.writeRelationships([{
+                    resourceType: "agent",
+                    resourceId: agentId,
+                    relation: "owner",
+                    subjectType: "person",
+                    subjectId: personId,
+                }]);
+            console.log(`Linked agent:${agentId} → person:${personId}`);
+        }
+        catch (err) {
+            console.error(`Failed to write identity link: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    });
+    // --------------------------------------------------------------------------
+    // unlink-identity — remove an agent→owner relationship from SpiceDB
+    // --------------------------------------------------------------------------
+    cmd
+        .command("unlink-identity")
+        .description("Remove an agent→owner relationship from SpiceDB")
+        .argument("<agent-id>", "Agent ID")
+        .action(async (agentId) => {
+        try {
+            const ownerId = await lookupAgentOwner(spicedb, agentId, getLastWriteToken());
+            if (!ownerId) {
+                console.log(`No owner link found for agent:${agentId}`);
+                return;
+            }
+            await spicedb.deleteRelationships([{
+                    resourceType: "agent",
+                    resourceId: agentId,
+                    relation: "owner",
+                    subjectType: "person",
+                    subjectId: ownerId,
+                }]);
+            console.log(`Unlinked agent:${agentId} (was → person:${ownerId})`);
+        }
+        catch (err) {
+            console.error(`Failed to remove identity link: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    });
+    // --------------------------------------------------------------------------
     // Backend-specific extension point
     // --------------------------------------------------------------------------
     backend.registerCliCommands?.(cmd);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contextableai/openclaw-memory-rebac",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "OpenClaw two-layer memory plugin: SpiceDB ReBAC authorization + Graphiti knowledge graph",
   "type": "module",
   "license": "MIT",