@contextableai/openclaw-memory-rebac 0.3.4 → 0.3.6

package/README.md

@@ -163,6 +163,25 @@ When enabled (default: `true`), the plugin captures the last N messages from eac
 - Skips messages shorter than 5 characters and injected context blocks
 - Uses custom extraction instructions for entity/fact extraction
 
+### Session Filtering
+
+Both auto-recall and auto-capture can be filtered by session key pattern using the `sessionFilter` config option. This is useful for excluding cron jobs, monitoring sessions, or other automated processes that generate repetitive, low-value data.
+
+```json
+{
+  "sessionFilter": {
+    "excludePatterns": ["cron", "monitoring", "healthcheck"]
+  }
+}
+```
+
+- **`excludePatterns`**: Array of strings. If the session key contains any of these substrings, auto-recall and auto-capture are skipped for that session.
+- **`includePatterns`**: Array of strings. If set, only sessions whose key contains at least one of these substrings will trigger auto-recall/capture.
+- If both are set, `excludePatterns` takes priority (exclude first, then check include).
+- If neither is set, all sessions are captured (default behavior).
+
+Filtered sessions still have full access to explicit memory tools (`memory_recall`, `memory_store`, `memory_forget`, `memory_status`). This means a cron job that consolidates memories can still use `memory_recall` and `memory_store` directly — only the automatic hooks are suppressed.
+
 ## Authorization Model
 
 The SpiceDB schema defines four object types:
@@ -270,6 +289,8 @@ Agents without an `identities` entry (like service agents) are not linked to any
 | `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 |
+| `sessionFilter.excludePatterns` | string[] | `[]` | Skip auto-capture/recall for sessions matching any pattern |
+| `sessionFilter.includePatterns` | string[] | `[]` | Only auto-capture/recall sessions matching at least one pattern |
 | `customInstructions` | string | *(see below)* | Custom extraction instructions |
 | `maxCaptureMessages` | integer | `10` | Max messages per auto-capture batch (1-50) |
 
@@ -389,7 +410,10 @@ OpenClaw has an exclusive `memory` slot — only one memory plugin is active at
             "my-agent": "U0123ABC"
           },
           "autoCapture": true,
-          "autoRecall": true
+          "autoRecall": true,
+          "sessionFilter": {
+            "excludePatterns": ["cron"]
+          }
         }
       }
     }

package/dist/backend.d.ts

@@ -74,7 +74,7 @@ export interface MemoryBackend {
     }): Promise<StoreResult>;
     /**
      * Search within a single group's storage partition.
-     * Called in parallel per-group by searchAuthorizedMemories() in search.ts.
+     * Fallback path when searchGroups() is not available.
      * Backends map their native result shape to SearchResult[].
      */
     searchGroup(params: {
@@ -83,6 +83,19 @@ export interface MemoryBackend {
         limit: number;
         sessionId?: string;
     }): Promise<SearchResult[]>;
+    /**
+     * Search across multiple groups in a single backend call.
+     * Preferred over per-group fan-out because the backend can apply its own
+     * cross-group relevance ranking (e.g. Graphiti's RRF: cosine + BM25).
+     * Results are ordered by relevance; response position is used as implicit score.
+     * Optional: falls back to per-group searchGroup() fan-out if not implemented.
+     */
+    searchGroups?(params: {
+        query: string;
+        groupIds: string[];
+        limit: number;
+        sessionId?: string;
+    }): Promise<SearchResult[]>;
     /**
      * Optional backend-specific session enrichment, called from agent_end
      * after store() for conversation auto-capture.

package/dist/backends/graphiti.d.ts

@@ -26,6 +26,7 @@ type FactResult = {
     invalid_at: string | null;
     created_at: string;
     expired_at: string | null;
+    group_id?: string;
 };
 export type GraphitiConfig = {
     endpoint: string;
@@ -56,6 +57,12 @@ export declare class GraphitiBackend implements MemoryBackend {
         limit: number;
         sessionId?: string;
     }): Promise<SearchResult[]>;
+    searchGroups(params: {
+        query: string;
+        groupIds: string[];
+        limit: number;
+        sessionId?: string;
+    }): Promise<SearchResult[]>;
     getConversationHistory(sessionId: string, lastN?: number): Promise<ConversationTurn[]>;
     healthCheck(): Promise<boolean>;
     getStatus(): Promise<Record<string, unknown>>;

package/dist/backends/graphiti.js

@@ -107,6 +107,29 @@ export class GraphitiBackend {
             created_at: f.created_at,
         }));
     }
+    async searchGroups(params) {
+        const { query, groupIds, limit } = params;
+        if (groupIds.length === 0)
+            return [];
+        const searchRequest = {
+            group_ids: groupIds,
+            query,
+            max_facts: limit,
+        };
+        const response = await this.restCall("POST", "/search", searchRequest);
+        const facts = response.facts ?? [];
+        // Derive implicit relevance score from response position —
+        // Graphiti's /search returns results ranked by RRF (cosine + BM25).
+        return facts.map((f, index) => ({
+            type: "fact",
+            uuid: f.uuid,
+            group_id: f.group_id ?? groupIds[0],
+            summary: f.fact,
+            context: f.name,
+            created_at: f.created_at,
+            score: 1.0 - index / Math.max(facts.length, 1),
+        }));
+    }
     async getConversationHistory(sessionId, lastN = 10) {
         const sessionGroup = `session-${sessionId.replace(/[^a-zA-Z0-9_-]/g, "-")}`;
         try {

package/dist/config.d.ts

@@ -21,6 +21,10 @@ export type RebacMemoryConfig = {
     autoCapture: boolean;
     autoRecall: boolean;
     maxCaptureMessages: number;
+    sessionFilter?: {
+        excludePatterns?: string[];
+        includePatterns?: string[];
+    };
 };
 export declare const rebacMemoryConfigSchema: {
     parse(value: unknown): RebacMemoryConfig;

package/dist/config.js

@@ -25,6 +25,21 @@ function assertAllowedKeys(value, allowed, label) {
         throw new Error(`${label} has unknown keys: ${unknown.join(", ")}`);
     }
 }
+function parseSessionFilter(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return undefined;
+    const obj = raw;
+    assertAllowedKeys(obj, ["excludePatterns", "includePatterns"], "sessionFilter config");
+    const excludePatterns = Array.isArray(obj.excludePatterns)
+        ? obj.excludePatterns.filter((p) => typeof p === "string")
+        : undefined;
+    const includePatterns = Array.isArray(obj.includePatterns)
+        ? obj.includePatterns.filter((p) => typeof p === "string")
+        : undefined;
+    if (!excludePatterns?.length && !includePatterns?.length)
+        return undefined;
+    return { excludePatterns, includePatterns };
+}
 // ============================================================================
 // Config schema
 // ============================================================================
@@ -42,7 +57,7 @@ export const rebacMemoryConfigSchema = {
         assertAllowedKeys(cfg, [
             "backend", "spicedb",
             "subjectType", "subjectId", "identities",
-            "autoCapture", "autoRecall", "maxCaptureMessages",
+            "autoCapture", "autoRecall", "maxCaptureMessages", "sessionFilter",
             backendName,
         ], "openclaw-memory-rebac config");
         // SpiceDB config (shared)
@@ -84,6 +99,7 @@ export const rebacMemoryConfigSchema = {
             maxCaptureMessages: typeof cfg.maxCaptureMessages === "number" && cfg.maxCaptureMessages > 0
                 ? cfg.maxCaptureMessages
                 : pluginDefaults.maxCaptureMessages,
+            sessionFilter: parseSessionFilter(cfg.sessionFilter),
         };
     },
 };

package/dist/index.js

@@ -22,7 +22,7 @@ import { fileURLToPath } from "node:url";
 import { rebacMemoryConfigSchema, createBackend, defaultGroupId } from "./config.js";
 import { SpiceDbClient } from "./spicedb.js";
 import { lookupAuthorizedGroups, lookupViewableFragments, lookupFragmentSourceGroups, lookupAgentOwner, writeFragmentRelationships, deleteFragmentRelationships, canDeleteFragment, canWriteToGroup, ensureGroupMembership, } from "./authorization.js";
-import { searchAuthorizedMemories, formatDualResults, deduplicateSessionResults, } from "./search.js";
+import { searchAuthorizedMemories, formatDualResults, } from "./search.js";
 import { registerCommands } from "./cli.js";
 // ============================================================================
 // Session helpers
@@ -34,6 +34,26 @@ function sessionGroupId(sessionId) {
 function isSessionGroup(groupId) {
     return groupId.startsWith("session-");
 }
+function isSessionAllowed(sessionKey, filter) {
+    if (!filter)
+        return true;
+    if (!sessionKey)
+        return true;
+    if (filter.excludePatterns?.length) {
+        for (const pattern of filter.excludePatterns) {
+            if (sessionKey.includes(pattern))
+                return false;
+        }
+    }
+    if (filter.includePatterns?.length) {
+        for (const pattern of filter.includePatterns) {
+            if (sessionKey.includes(pattern))
+                return true;
+        }
+        return false;
+    }
+    return true;
+}
 // ============================================================================
 // Plugin Definition
 // ============================================================================
@@ -131,27 +151,21 @@ const rebacMemoryPlugin = {
                             sessionGroups.push(sg);
                     }
                 }
-                // Group-based search (existing path)
-                const [longTermResults, rawSessionResults] = await Promise.all([
-                    longTermGroups.length > 0
-                        ? searchAuthorizedMemories(backend, {
-                            query,
-                            groupIds: longTermGroups,
-                            limit,
-                            sessionId: state.sessionId,
-                        })
-                        : Promise.resolve([]),
-                    sessionGroups.length > 0
-                        ? searchAuthorizedMemories(backend, {
-                            query,
-                            groupIds: sessionGroups,
-                            limit,
-                            sessionId: state.sessionId,
-                        })
-                        : Promise.resolve([]),
-                ]);
-                const sessionResults = deduplicateSessionResults(longTermResults, rawSessionResults);
-                const groupResults = [...longTermResults, ...sessionResults];
+                // Single multi-group search — lets the backend rank all results together
+                const allGroups = [...longTermGroups, ...sessionGroups];
+                const allGroupResults = allGroups.length > 0
+                    ? await searchAuthorizedMemories(backend, {
+                        query,
+                        groupIds: allGroups,
+                        limit,
+                        sessionId: state.sessionId,
+                    })
+                    : [];
+                // Split results by group type for formatting
+                const sessionGroupSet = new Set(sessionGroups);
+                const longTermResults = allGroupResults.filter((r) => !sessionGroupSet.has(r.group_id));
+                const sessionResults = allGroupResults.filter((r) => sessionGroupSet.has(r.group_id));
+                const groupResults = allGroupResults;
                 // Owner-aware fragment search: if the subject is an agent with an owner,
                 // also find fragments where the owner is in `involves`.
                 // Uses search-then-post-filter: search the source groups for query relevance,
@@ -466,6 +480,8 @@ const rebacMemoryPlugin = {
                 const state = getState(ctx?.agentId);
                 if (ctx?.sessionKey)
                     state.sessionId = ctx.sessionKey;
+                if (!isSessionAllowed(ctx?.sessionKey, cfg.sessionFilter))
+                    return;
                 if (!event.prompt || event.prompt.length < 5)
                     return;
                 try {
@@ -477,26 +493,20 @@ const rebacMemoryPlugin = {
                         if (!sessionGroups.includes(sg))
                             sessionGroups.push(sg);
                     }
-                    const [longTermResults, rawSessionResults] = await Promise.all([
-                        longTermGroups.length > 0
-                            ? searchAuthorizedMemories(backend, {
-                                query: event.prompt,
-                                groupIds: longTermGroups,
-                                limit: 5,
-                                sessionId: state.sessionId,
-                            })
-                            : Promise.resolve([]),
-                        sessionGroups.length > 0
-                            ? searchAuthorizedMemories(backend, {
-                                query: event.prompt,
-                                groupIds: sessionGroups,
-                                limit: 3,
-                                sessionId: state.sessionId,
-                            })
-                            : Promise.resolve([]),
-                    ]);
-                    const sessionResults = deduplicateSessionResults(longTermResults, rawSessionResults);
-                    const totalCount = longTermResults.length + sessionResults.length;
+                    const autoRecallLimit = 8;
+                    const allGroups = [...longTermGroups, ...sessionGroups];
+                    const allResults = allGroups.length > 0
+                        ? await searchAuthorizedMemories(backend, {
+                            query: event.prompt,
+                            groupIds: allGroups,
+                            limit: autoRecallLimit,
+                            sessionId: state.sessionId,
+                        })
+                        : [];
+                    const sessionGroupSet = new Set(sessionGroups);
+                    const longTermResults = allResults.filter((r) => !sessionGroupSet.has(r.group_id));
+                    const sessionResults = allResults.filter((r) => sessionGroupSet.has(r.group_id));
+                    const totalCount = allResults.length;
                     const toolHint = "<memory-tools>\n" +
                         "You have knowledge-graph memory tools. Use them proactively:\n" +
                         "- memory_recall: Search for facts, preferences, people, decisions, or past context. Use this BEFORE saying you don't know or remember something.\n" +
@@ -521,6 +531,8 @@ const rebacMemoryPlugin = {
                 const state = getState(ctx?.agentId);
                 if (ctx?.sessionKey)
                     state.sessionId = ctx.sessionKey;
+                if (!isSessionAllowed(ctx?.sessionKey, cfg.sessionFilter))
+                    return;
                 if (!event.success || !event.messages || event.messages.length === 0)
                     return;
                 try {

package/dist/search.d.ts

@@ -1,9 +1,9 @@
 /**
- * Parallel Multi-Group Search + Merge/Re-rank
+ * Multi-Group Search with backend-native relevance ranking.
  *
- * 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.
+ * Prefers MemoryBackend.searchGroups() — a single call with all group_ids
+ * so the backend applies cross-group relevance ranking (e.g. Graphiti RRF).
+ * Falls back to per-group fan-out via searchGroup() when unavailable.
  */
 import type { MemoryBackend, SearchResult } from "./backend.js";
 export type { SearchResult };
@@ -14,9 +14,14 @@ export type SearchOptions = {
     sessionId?: string;
 };
 /**
- * Search across multiple authorized group_ids in parallel.
- * Merges and deduplicates results, returning up to `limit` items sorted by
- * score (desc) then recency (desc).
+ * Search across multiple authorized group_ids.
+ *
+ * Prefers backend.searchGroups() when available — sends all group_ids in a
+ * single call so the backend can apply cross-group relevance ranking
+ * (e.g. Graphiti's RRF: cosine similarity + BM25).
+ *
+ * Falls back to per-group fan-out via backend.searchGroup() when the backend
+ * doesn't implement multi-group search.
  */
 export declare function searchAuthorizedMemories(backend: MemoryBackend, options: SearchOptions): Promise<SearchResult[]>;
 /**
@@ -28,7 +33,3 @@ export declare function formatResultsForContext(results: SearchResult[]): string
  * Session group_ids start with "session-".
  */
 export declare function formatDualResults(longTermResults: SearchResult[], sessionResults: SearchResult[]): string;
-/**
- * Deduplicate session results against long-term results (by UUID).
- */
-export declare function deduplicateSessionResults(longTermResults: SearchResult[], sessionResults: SearchResult[]): SearchResult[];

package/dist/search.js

@@ -1,24 +1,41 @@
 /**
- * Parallel Multi-Group Search + Merge/Re-rank
+ * Multi-Group Search with backend-native relevance ranking.
  *
- * 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.
+ * Prefers MemoryBackend.searchGroups() — a single call with all group_ids
+ * so the backend applies cross-group relevance ranking (e.g. Graphiti RRF).
+ * Falls back to per-group fan-out via searchGroup() when unavailable.
  */
 // ============================================================================
 // 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).
+ * Search across multiple authorized group_ids.
+ *
+ * Prefers backend.searchGroups() when available — sends all group_ids in a
+ * single call so the backend can apply cross-group relevance ranking
+ * (e.g. Graphiti's RRF: cosine similarity + BM25).
+ *
+ * Falls back to per-group fan-out via backend.searchGroup() when the backend
+ * doesn't implement multi-group search.
  */
 export async function searchAuthorizedMemories(backend, options) {
     const { query, groupIds, limit = 10, sessionId } = options;
     if (groupIds.length === 0) {
         return [];
     }
-    // Fan out parallel searches across all authorized groups
+    // Prefer single multi-group search — preserves backend relevance ranking
+    if (backend.searchGroups) {
+        const results = await backend.searchGroups({ query, groupIds, limit, sessionId });
+        // Deduplicate by UUID (defensive — single call shouldn't produce dupes)
+        const seen = new Set();
+        return results.filter((r) => {
+            if (seen.has(r.uuid))
+                return false;
+            seen.add(r.uuid);
+            return true;
+        }).slice(0, limit);
+    }
+    // Fallback: 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
@@ -89,10 +106,3 @@ function formatResultLine(r, idx) {
                     "completion";
     return `${idx}. [${typeLabel}:${r.uuid}] ${r.summary} (${r.context})`;
 }
-/**
- * Deduplicate session results against long-term results (by UUID).
- */
-export function deduplicateSessionResults(longTermResults, sessionResults) {
-    const longTermIds = new Set(longTermResults.map((r) => r.uuid));
-    return sessionResults.filter((r) => !longTermIds.has(r.uuid));
-}

package/docker/graphiti/Dockerfile

@@ -5,9 +5,19 @@
 # Extends the base zepai/graphiti image to:
 #   1. Install sentence-transformers for BGE reranker
 #   2. Overlay per-component config + startup to wire separate clients
+#
+# UPGRADE AUDIT (vs upstream getzep/graphiti v0.28.2, audited 2026-03-21):
+#   Overlay patches in startup.py — 5 of 6 still needed:
+#   [NEEDED]  AsyncWorker crash-on-error recovery      (startup.py:109-126)
+#   [NEEDED]  Neo4j nested attribute sanitization       (startup.py:128-250)
+#   [SAFE]    None-index extract_edges fix              (startup.py:252-298)
+#             — fixed upstream (name-based model); patch self-disables
+#   [NEEDED]  IS_DUPLICATE_OF edge filtering            (startup.py:152-169,216-227,310-318)
+#   [NEEDED]  Self-referential edge filtering           (startup.py:228-239)
+#   [NEEDED]  Singleton client / per-request fix        (startup.py:38-87)
 ###############################################################################
 
-FROM zepai/graphiti:latest
+FROM zepai/graphiti:0.22.0
 
 # Base image runs as non-root "app" user; switch to root to install packages
 USER root

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contextableai/openclaw-memory-rebac",
-  "version": "0.3.4",
+  "version": "0.3.6",
   "description": "OpenClaw two-layer memory plugin: SpiceDB ReBAC authorization + Graphiti knowledge graph",
   "type": "module",
   "license": "MIT",
@@ -43,16 +43,16 @@
     "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",
+    "@authzed/authzed-node": "1.6.1",
+    "@grpc/grpc-js": "1.14.3",
     "@sinclair/typebox": "0.34.48",
-    "commander": "^13.1.0"
+    "commander": "13.1.0"
   },
   "devDependencies": {
-    "dotenv": "^17.3.1",
+    "dotenv": "17.3.1",
     "openclaw": "*",
-    "typescript": "^5.9.3",
-    "vitest": "^4.0.18"
+    "typescript": "5.9.3",
+    "vitest": "4.0.18"
   },
   "publishConfig": {
     "access": "public"
@@ -62,7 +62,7 @@
       "./dist/index.js"
     ],
     "install": {
-      "npmSpec": "@contextableai/openclaw-memory-rebac",
+      "npmSpec": "@contextableai/openclaw-memory-rebac@0.3.5",
       "localPath": "extensions/openclaw-memory-rebac",
       "defaultChoice": "npm"
     }