@contextableai/openclaw-memory-rebac 0.3.7 → 0.4.0

package/README.md

@@ -49,6 +49,26 @@ This means you can change your storage engine without touching authorization, an
 - **Docker image**: Custom image (`docker/graphiti/`) with per-component LLM/embedder/reranker configuration, BGE reranker support, and runtime patches for local-model compatibility
 - **Best for**: Rich entity-relationship extraction, structured knowledge
 
+### EverMemOS
+
+[EverMemOS](https://github.com/EverMind-AI/EverMemOS) is a memory system with MemCell boundary detection and parallel LLM extraction. It produces richer memory types — episodic memories, user profiles, foresight (predictions), and event logs.
+
+- **Storage**: MongoDB + Milvus (vector) + Elasticsearch (keyword)
+- **Transport**: REST API to EverMemOS FastAPI server (port 1995)
+- **Extraction**: MemCell pipeline — automatic boundary detection, then parallel LLM extraction of multiple memory types
+- **Search**: Hybrid (vector + keyword + reranking), configurable via `retrieveMethod`
+- **Docker image**: Built from source (`docker/evermemos/Dockerfile`), pinned to upstream release tag (v1.1.0)
+- **Best for**: Rich memory type diversity, foresight extraction, hybrid search
+- **Limitation**: No `involves` at ingestion — use `memory_share` for post-hoc cross-group sharing
+
+#### EverMemOS-specific config
+
+| Key | Default | Description |
+|---|---|---|
+| `retrieveMethod` | `"hybrid"` | Search method: `"hybrid"`, `"vector"`, `"keyword"` |
+| `memoryTypes` | `["episodic_memory", "profile", "foresight", "event_log"]` | Which memory types to search |
+| `defaultSenderId` | `"system"` | Sender ID for stored messages |
+
 ## Installation
 
 ```bash
@@ -68,22 +88,35 @@ Then restart the gateway. On first start, the plugin automatically:
 ### Prerequisites
 
 - [Docker](https://docs.docker.com/get-docker/) and Docker Compose
-- A running LLM endpoint (Graphiti uses an LLM for entity extraction and embeddings)
+- A running LLM endpoint (both backends use LLMs for memory extraction)
 
 ### 1. Start Infrastructure
 
+**Option A: Graphiti backend (default)**
+
 ```bash
 cd docker
 cp graphiti/.env.example graphiti/.env
 # Edit graphiti/.env — set your LLM endpoint and API key
-docker compose up -d
+docker compose -f docker-compose.graphiti.yml up -d
 ```
 
-This starts the full stack:
-- **Neo4j** on port 7687 (graph database, browser on port 7474)
-- **Graphiti** on port 8000 (FastAPI REST server)
-- **PostgreSQL** on port 5432 (persistent datastore for SpiceDB)
-- **SpiceDB** on port 50051 (authorization engine)
+This starts: Neo4j (7687), Graphiti (8000), PostgreSQL (5432), SpiceDB (50051).
+
+**Option B: EverMemOS backend**
+
+```bash
+cd docker/evermemos
+cp .env.example .env
+# Edit .env — set LLM_API_KEY, VECTORIZE_API_KEY, RERANK_API_KEY
+
+cd docker
+docker compose -f docker-compose.evermemos.yml up -d
+```
+
+This starts: EverMemOS all-in-one container (1995), PostgreSQL (5432), SpiceDB (50051). First run builds the image from source (~5 min).
+
+Both options share the same SpiceDB instance with the same authorization schema.
 
 ### 2. Restart the Gateway
 
@@ -446,14 +479,18 @@ rebac-mem import --include-sessions
 
 ## Docker Compose
 
-The `docker/` directory contains a modular Docker Compose stack. The top-level `docker/docker-compose.yml` includes both sub-stacks:
+The `docker/` directory contains modular Docker Compose stacks. Two top-level compose files select which memory backend to pair with SpiceDB:
 
 ```bash
-# Start the full stack (Graphiti + SpiceDB)
-cd docker
-docker compose up -d
+# Graphiti + SpiceDB
+cd docker && docker compose -f docker-compose.graphiti.yml up -d
+
+# EverMemOS + SpiceDB
+cd docker && docker compose -f docker-compose.evermemos.yml up -d
 ```
 
+Both share the same SpiceDB sub-stack — same authorization schema, same permissions model.
+
 ### Graphiti Stack (`docker/graphiti/`)
 
 | Service | Port | Description |
@@ -475,12 +512,31 @@ The custom Docker image extends `zepai/graphiti:latest` with:
 | `spicedb-migrate` | — | One-shot: runs SpiceDB DB migrations |
 | `spicedb` | 50051, 8080 | Authorization engine (gRPC, HTTP health) |
 
+### EverMemOS Stack (`docker/evermemos/`)
+
+Single all-in-one container bundling all required services via supervisord:
+
+| Component | Internal Port | Description |
+|-----------|---------------|-------------|
+| MongoDB 7.0 | 27017 | Document store |
+| Elasticsearch 8 | 9200 | Keyword search |
+| Milvus v2.5.2 | 19530 | Vector database (standalone with embedded etcd) |
+| Redis 7 | 6379 | Cache |
+| EverMemOS API | **1995 (exposed)** | FastAPI server (built from source) |
+
+The image is built from the [EverMemOS](https://github.com/EverMind-AI/EverMemOS) repository, pinned to release tag `v1.1.0`. Update `EVERMEMOS_VERSION` in `docker/evermemos/docker-compose.yml` to upgrade. Requires ~4 GB RAM.
+
+Requires API keys in `docker/evermemos/.env` for LLM, embedding (vectorize), and reranking services. See `.env.example` for all options.
+
 ### Running Stacks Independently
 
 ```bash
 # Graphiti only
 cd docker/graphiti && docker compose up -d
 
+# EverMemOS only (without SpiceDB)
+cd docker/evermemos && docker compose up -d
+
 # SpiceDB only
 cd docker/spicedb && docker compose up -d
 ```
@@ -511,11 +567,14 @@ OPENCLAW_LIVE_TEST=1 npm run test:e2e
 ├── openclaw.plugin.json      # Plugin manifest
 ├── package.json
 ├── backends/
-│   └── graphiti.ts           # Graphiti REST backend implementation
+│   ├── graphiti.ts           # Graphiti REST backend implementation
+│   ├── evermemos.ts          # EverMemOS REST backend implementation
+│   └── registry.ts           # Static backend registry
 ├── bin/
 │   └── rebac-mem.ts          # Standalone CLI entry point
 ├── docker/
-│   ├── docker-compose.yml    # Combined stack (includes both sub-stacks)
+│   ├── docker-compose.graphiti.yml   # Graphiti + SpiceDB
+│   ├── docker-compose.evermemos.yml # EverMemOS + SpiceDB
 │   ├── graphiti/
 │   │   ├── docker-compose.yml
 │   │   ├── Dockerfile        # Custom Graphiti image with patches
@@ -523,10 +582,17 @@ OPENCLAW_LIVE_TEST=1 npm run test:e2e
 │   │   ├── graphiti_overlay.py # OpenClawGraphiti class
 │   │   ├── startup.py        # Runtime patches and uvicorn launch
 │   │   └── .env.example
+│   ├── evermemos/
+│   │   ├── docker-compose.yml # EverMemOS all-in-one container
+│   │   ├── Dockerfile         # All-in-one: MongoDB+ES+Milvus+Redis+EverMemOS
+│   │   ├── supervisord.conf   # Process manager config
+│   │   └── .env.example       # LLM, vectorize, rerank API keys
 │   └── spicedb/
 │       └── docker-compose.yml
-├── *.test.ts                 # Unit tests (96)
-├── e2e.test.ts               # End-to-end tests (15, live services)
+├── *.test.ts                 # Unit tests (178)
+├── e2e.test.ts               # Graphiti E2E tests (14, live services)
+├── e2e-backend.test.ts       # Backend-agnostic E2E contract (13)
+├── e2e-evermemos.test.ts     # EverMemOS-specific E2E (7)
 ├── vitest.config.ts          # Unit test config
 └── vitest.e2e.config.ts      # E2E test config
 ```

package/dist/authorization.d.ts

@@ -66,3 +66,23 @@ export declare function lookupFragmentSourceGroups(spicedb: SpiceDbClient, fragm
  * Idempotent (uses TOUCH operation).
  */
 export declare function ensureGroupMembership(spicedb: SpiceDbClient, groupId: string, member: Subject): Promise<string | undefined>;
+/**
+ * Ensure a subject is registered as an owner of a group.
+ * Owners have admin permission (can share memories from their groups).
+ * Idempotent (uses TOUCH operation).
+ */
+export declare function ensureGroupOwnership(spicedb: SpiceDbClient, groupId: string, owner: Subject): Promise<string | undefined>;
+/**
+ * Check if a subject has share permission on a memory fragment.
+ * Share is granted to: shared_by (storer) + source_group->admin (group owners).
+ */
+export declare function canShareFragment(spicedb: SpiceDbClient, subject: Subject, fragmentId: string, zedToken?: string): Promise<boolean>;
+/**
+ * Share a memory fragment with one or more subjects by writing `involves` relationships.
+ * This grants view permission to the targets (and their agents via involves->represents).
+ */
+export declare function shareFragment(spicedb: SpiceDbClient, fragmentId: string, targets: Subject[]): Promise<string | undefined>;
+/**
+ * Unshare a memory fragment by removing `involves` relationships for the given targets.
+ */
+export declare function unshareFragment(spicedb: SpiceDbClient, fragmentId: string, targets: Subject[]): Promise<void>;

package/dist/authorization.js

@@ -166,3 +166,63 @@ export async function ensureGroupMembership(spicedb, groupId, member) {
         },
     ]);
 }
+/**
+ * Ensure a subject is registered as an owner of a group.
+ * Owners have admin permission (can share memories from their groups).
+ * Idempotent (uses TOUCH operation).
+ */
+export async function ensureGroupOwnership(spicedb, groupId, owner) {
+    return spicedb.writeRelationships([
+        {
+            resourceType: "group",
+            resourceId: groupId,
+            relation: "owner",
+            subjectType: owner.type,
+            subjectId: owner.id,
+        },
+    ]);
+}
+// ============================================================================
+// Share / Unshare
+// ============================================================================
+/**
+ * Check if a subject has share permission on a memory fragment.
+ * Share is granted to: shared_by (storer) + source_group->admin (group owners).
+ */
+export async function canShareFragment(spicedb, subject, fragmentId, zedToken) {
+    return spicedb.checkPermission({
+        resourceType: "memory_fragment",
+        resourceId: fragmentId,
+        permission: "share",
+        subjectType: subject.type,
+        subjectId: subject.id,
+        consistency: tokenConsistency(zedToken),
+    });
+}
+/**
+ * Share a memory fragment with one or more subjects by writing `involves` relationships.
+ * This grants view permission to the targets (and their agents via involves->represents).
+ */
+export async function shareFragment(spicedb, fragmentId, targets) {
+    const tuples = targets.map((target) => ({
+        resourceType: "memory_fragment",
+        resourceId: fragmentId,
+        relation: "involves",
+        subjectType: target.type,
+        subjectId: target.id,
+    }));
+    return spicedb.writeRelationships(tuples);
+}
+/**
+ * Unshare a memory fragment by removing `involves` relationships for the given targets.
+ */
+export async function unshareFragment(spicedb, fragmentId, targets) {
+    const tuples = targets.map((target) => ({
+        resourceType: "memory_fragment",
+        resourceId: fragmentId,
+        relation: "involves",
+        subjectType: target.type,
+        subjectId: target.id,
+    }));
+    await spicedb.deleteRelationships(tuples);
+}

package/dist/backend.d.ts

@@ -31,6 +31,10 @@ export type SearchResult = {
  * registered in SpiceDB.
  *
  * - Graphiti: Resolves once the server has processed the episode (polled in the background).
+ * - EverMemOS: Resolves immediately to our generated message_id UUID. This anchor is used
+ *   for share/involves SpiceDB relationships. Note: search result IDs (MongoDB ObjectIds)
+ *   differ from this anchor, so involves-based cross-group recall post-filtering won't
+ *   match — group-level access handles the common path.
  *
  * index.ts chains SpiceDB writeFragmentRelationships() to this Promise,
  * so it always fires at the right time.
@@ -138,6 +142,20 @@ export interface MemoryBackend {
      * Optional: not all backends separate episodes from fragments.
      */
     discoverFragmentIds?(episodeId: string): Promise<string[]>;
+    /**
+     * Resolve anchor IDs (e.g. message UUIDs written to SpiceDB during store)
+     * to actual searchable fragment IDs (e.g. MongoDB ObjectIds).
+     *
+     * Called during recall when viewable fragment IDs from SpiceDB don't match
+     * any search results — indicates the anchors were written before extraction
+     * completed (discoverFragmentIds timed out).
+     *
+     * Returns a Map of anchor → resolved fragment IDs. Only anchors that
+     * successfully resolved are included; unresolvable anchors are omitted.
+     *
+     * Optional: backends where store IDs match search IDs don't need this.
+     */
+    resolveAnchors?(anchorIds: string[]): Promise<Map<string, string[]>>;
     /**
      * Register backend-specific CLI subcommands onto the shared `rebac-mem` command.
      * Called once during CLI setup. Backend may register any commands it needs.

package/dist/backends/evermemos.d.ts

@@ -0,0 +1,84 @@
+/**
+ * EverMemOSBackend — MemoryBackend implementation backed by the EverMemOS FastAPI REST server.
+ *
+ * EverMemOS communicates via standard HTTP REST endpoints on port 1995.
+ * Messages are processed through the MemCell pipeline: boundary detection →
+ * parallel LLM extraction of episodic memories, foresight, event logs, and profiles.
+ *
+ * store() returns immediately with a generated message_id as the fragment anchor.
+ * With @timeout_to_background(), store may return 202 Accepted for background processing.
+ *
+ * discoverFragmentIds() polls a custom trace overlay endpoint to resolve the message_id
+ * to actual MongoDB ObjectIds of derived memories. These ObjectIds are what search
+ * results return, enabling fragment-level SpiceDB authorization (involves, share).
+ *
+ * resolveAnchors() provides lazy resolution at recall time: if discoverFragmentIds()
+ * timed out during store, unresolved anchors can be resolved later when someone
+ * actually tries to recall the involved fragments.
+ */
+import type { Command } from "commander";
+import type { MemoryBackend, SearchResult, StoreResult, ConversationTurn, BackendDataset } from "../backend.js";
+export type EverMemOSConfig = {
+    endpoint: string;
+    defaultGroupId: string;
+    requestTimeoutMs: number;
+    retrieveMethod: string;
+    memoryTypes: string[];
+    defaultSenderId: string;
+    discoveryPollIntervalMs: number;
+    discoveryTimeoutMs: number;
+};
+export declare class EverMemOSBackend implements MemoryBackend {
+    private readonly config;
+    readonly name = "evermemos";
+    private readonly requestTimeoutMs;
+    /**
+     * Tracks pending stores: messageId → groupId.
+     * Populated by store(), consumed by discoverFragmentIds().
+     */
+    private readonly pendingStores;
+    constructor(config: EverMemOSConfig);
+    private restCall;
+    store(params: {
+        content: string;
+        groupId: string;
+        sourceDescription?: string;
+        customPrompt?: string;
+    }): Promise<StoreResult>;
+    searchGroup(params: {
+        query: string;
+        groupId: string;
+        limit: number;
+        sessionId?: string;
+    }): Promise<SearchResult[]>;
+    enrichSession(params: {
+        sessionId: string;
+        groupId: string;
+        userMsg: string;
+        assistantMsg: string;
+    }): Promise<void>;
+    getConversationHistory(sessionId: string, lastN?: number): Promise<ConversationTurn[]>;
+    healthCheck(): Promise<boolean>;
+    getStatus(): Promise<Record<string, unknown>>;
+    deleteGroup(groupId: string): Promise<void>;
+    listGroups(): Promise<BackendDataset[]>;
+    deleteFragment(uuid: string, _type?: string): Promise<boolean>;
+    /**
+     * Poll the trace overlay endpoint to discover MongoDB ObjectIds of derived
+     * memories (episodic, foresight, event_log) produced from a stored message.
+     *
+     * Called by index.ts after store() resolves the fragmentId Promise.
+     * Returns ObjectIds that match what search results return, enabling
+     * fragment-level SpiceDB authorization (involves, share/unshare).
+     */
+    discoverFragmentIds(messageId: string): Promise<string[]>;
+    /**
+     * Lazy resolution: resolve unmatched SpiceDB anchor UUIDs to actual
+     * searchable fragment IDs. Called during recall when viewable fragment IDs
+     * from SpiceDB don't match any search results.
+     */
+    resolveAnchors(anchorIds: string[]): Promise<Map<string, string[]>>;
+    registerCliCommands(cmd: Command): void;
+}
+export declare const defaults: Record<string, unknown>;
+export declare function create(config: Record<string, unknown>): MemoryBackend;

package/dist/backends/evermemos.defaults.json

@@ -0,0 +1,10 @@
+{
+  "endpoint": "http://localhost:1995",
+  "defaultGroupId": "main",
+  "requestTimeoutMs": 30000,
+  "retrieveMethod": "hybrid",
+  "memoryTypes": ["episodic_memory", "profile", "foresight", "event_log"],
+  "defaultSenderId": "system",
+  "discoveryPollIntervalMs": 3000,
+  "discoveryTimeoutMs": 120000
+}