@contextableai/openclaw-memory-rebac 0.3.7 → 0.4.0

package/dist/index.js

@@ -21,7 +21,7 @@ import { join, dirname } from "node:path";
 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 { lookupAuthorizedGroups, lookupViewableFragments, lookupFragmentSourceGroups, lookupAgentOwner, writeFragmentRelationships, deleteFragmentRelationships, canDeleteFragment, canWriteToGroup, ensureGroupMembership, ensureGroupOwnership, canShareFragment, shareFragment, unshareFragment, } from "./authorization.js";
 import { searchAuthorizedMemories, formatDualResults, } from "./search.js";
 import { registerCommands } from "./cli.js";
 // ============================================================================
@@ -55,6 +55,30 @@ function isSessionAllowed(sessionKey, filter) {
     return true;
 }
 // ============================================================================
+// Content sanitization
+// ============================================================================
+/**
+ * Strip OpenClaw envelope metadata from message text before Graphiti ingestion.
+ * Removes channel headers, sender/message-id meta lines, and memory injection
+ * blocks that would pollute entity extraction.
+ */
+export function stripEnvelopeMetadata(text) {
+    let result = text;
+    // Strip envelope header: [ChannelName ...metadata...] at start of line
+    // Matches: [Telegram Dev Chat +5m 2025-01-02T03:04Z] body
+    result = result.replace(/^\[[A-Z][^\]\n]*\]\s*/gm, "");
+    // Strip [from: SenderLabel] trailer lines
+    result = result.replace(/^\[from:\s*[^\]]*\]\s*$/gm, "");
+    // Strip [message_id: ...] hint lines
+    result = result.replace(/^\[message_id:\s*[^\]]*\]\s*$/gm, "");
+    // Strip memory injection blocks
+    result = result.replace(/<relevant-memories>[\s\S]*?<\/relevant-memories>/g, "");
+    result = result.replace(/<memory-tools>[\s\S]*?<\/memory-tools>/g, "");
+    // Collapse excess blank lines and trim
+    result = result.replace(/\n{3,}/g, "\n\n").trim();
+    return result;
+}
+// ============================================================================
 // Plugin Definition
 // ============================================================================
 const rebacMemoryPlugin = {
@@ -194,6 +218,40 @@ const rebacMemoryPlugin = {
                                         // Post-filter: only keep results the owner is authorized to view
                                         const viewableSet = new Set(newIds);
                                         ownerFragmentResults = candidateResults.filter(r => viewableSet.has(r.uuid));
+                                        // Lazy resolution: if post-filter found nothing but we had viewable
+                                        // fragment IDs and candidate results, the IDs may be unresolved
+                                        // anchors (e.g. messageId UUIDs from a timed-out discoverFragmentIds).
+                                        // Try resolving them to actual searchable IDs via the backend.
+                                        if (ownerFragmentResults.length === 0 && candidateResults.length > 0 && backend.resolveAnchors) {
+                                            const resolved = await backend.resolveAnchors(newIds);
+                                            if (resolved.size > 0) {
+                                                const resolvedSet = new Set([...resolved.values()].flat());
+                                                ownerFragmentResults = candidateResults.filter(r => resolvedSet.has(r.uuid));
+                                                // Background: update SpiceDB so future recalls are fast
+                                                if (ownerFragmentResults.length > 0) {
+                                                    void (async () => {
+                                                        try {
+                                                            for (const [, objectIds] of resolved) {
+                                                                for (const objId of objectIds) {
+                                                                    const wt = await writeFragmentRelationships(spicedb, {
+                                                                        fragmentId: objId,
+                                                                        groupId: newGroups[0],
+                                                                        sharedBy: ownerSubject,
+                                                                        involves: [ownerSubject],
+                                                                    });
+                                                                    if (wt)
+                                                                        state.lastWriteToken = wt;
+                                                                }
+                                                            }
+                                                            api.logger.info(`openclaw-memory-rebac: lazy-resolved ${resolved.size} anchor(s) to ${ownerFragmentResults.length} fragment(s)`);
+                                                        }
+                                                        catch (lazyErr) {
+                                                            api.logger.warn(`openclaw-memory-rebac: lazy SpiceDB update failed: ${String(lazyErr)}`);
+                                                        }
+                                                    })();
+                                                }
+                                            }
+                                        }
                                     }
                                 }
                             }
@@ -302,6 +360,11 @@ const rebacMemoryPlugin = {
                 // has a stable episode UUID.  Discover extracted fact UUIDs and write
                 // per-fact relationships so that fragment-level permissions (view, delete)
                 // resolve correctly against the IDs returned by memory_recall.
+                //
+                // Graphiti: polls /episodes/{id}/edges for fact UUIDs.
+                // EverMemOS: polls trace overlay for MongoDB ObjectIds of derived memories.
+                // If discovery times out, fallback writes the episode UUID itself — lazy
+                // resolution at recall time (resolveAnchors) handles the recovery.
                 result.fragmentId
                     .then(async (episodeId) => {
                     const factIds = backend.discoverFragmentIds
@@ -420,6 +483,93 @@ const rebacMemoryPlugin = {
                 };
             },
         }), { name: "memory_forget" });
+        api.registerTool((ctx) => ({
+            name: "memory_share",
+            label: "Memory Share",
+            description: "Share a specific memory with one or more people/agents, granting them view access. " +
+                "Use type-prefixed IDs from memory_recall (e.g. 'fact:UUID', 'chunk:UUID'). " +
+                "Only the memory's creator or a group admin can share.",
+            parameters: Type.Object({
+                id: Type.String({ description: "Memory ID to share (e.g. 'fact:da8650cb-...' or bare UUID)" }),
+                share_with: Type.Array(Type.String(), { description: "Person or agent IDs to grant view access" }),
+            }),
+            async execute(_toolCallId, params) {
+                const { id, share_with } = params;
+                if (share_with.length === 0) {
+                    return {
+                        content: [{ type: "text", text: "No targets specified." }],
+                        details: { action: "error", id },
+                    };
+                }
+                const subject = resolveSubject(ctx.agentId);
+                const state = getState(ctx.agentId);
+                // Parse type prefix to get bare UUID
+                const colonIdx = id.indexOf(":");
+                const uuid = colonIdx > 0 && colonIdx < 10 ? id.slice(colonIdx + 1) : id;
+                // Check share permission
+                const allowed = await canShareFragment(spicedb, subject, uuid, state.lastWriteToken);
+                if (!allowed) {
+                    return {
+                        content: [{ type: "text", text: `Permission denied: cannot share fragment "${uuid}". Only the creator or a group admin can share.` }],
+                        details: { action: "denied", id },
+                    };
+                }
+                // Write involves relationships for each target
+                const targets = share_with.map((targetId) => ({
+                    type: "person",
+                    id: targetId,
+                }));
+                const writeToken = await shareFragment(spicedb, uuid, targets);
+                if (writeToken)
+                    state.lastWriteToken = writeToken;
+                return {
+                    content: [{ type: "text", text: `Shared memory "${uuid}" with: ${share_with.join(", ")}` }],
+                    details: { action: "shared", id, uuid, targets: share_with },
+                };
+            },
+        }), { name: "memory_share" });
+        api.registerTool((ctx) => ({
+            name: "memory_unshare",
+            label: "Memory Unshare",
+            description: "Revoke view access to a specific memory for one or more people/agents. " +
+                "Removes the 'involves' relationship. Only the memory's creator or a group admin can unshare.",
+            parameters: Type.Object({
+                id: Type.String({ description: "Memory ID to unshare (e.g. 'fact:da8650cb-...' or bare UUID)" }),
+                revoke_from: Type.Array(Type.String(), { description: "Person or agent IDs to revoke view access from" }),
+            }),
+            async execute(_toolCallId, params) {
+                const { id, revoke_from } = params;
+                if (revoke_from.length === 0) {
+                    return {
+                        content: [{ type: "text", text: "No targets specified." }],
+                        details: { action: "error", id },
+                    };
+                }
+                const subject = resolveSubject(ctx.agentId);
+                const state = getState(ctx.agentId);
+                // Parse type prefix to get bare UUID
+                const colonIdx = id.indexOf(":");
+                const uuid = colonIdx > 0 && colonIdx < 10 ? id.slice(colonIdx + 1) : id;
+                // Check share permission (same permission governs unshare)
+                const allowed = await canShareFragment(spicedb, subject, uuid, state.lastWriteToken);
+                if (!allowed) {
+                    return {
+                        content: [{ type: "text", text: `Permission denied: cannot unshare fragment "${uuid}".` }],
+                        details: { action: "denied", id },
+                    };
+                }
+                // Remove involves relationships for each target
+                const targets = revoke_from.map((targetId) => ({
+                    type: "person",
+                    id: targetId,
+                }));
+                await unshareFragment(spicedb, uuid, targets);
+                return {
+                    content: [{ type: "text", text: `Revoked access to "${uuid}" from: ${revoke_from.join(", ")}` }],
+                    details: { action: "unshared", id, uuid, targets: revoke_from },
+                };
+            },
+        }), { name: "memory_unshare" });
         api.registerTool((ctx) => ({
             name: "memory_status",
             label: "Memory Status",
@@ -566,9 +716,8 @@ const rebacMemoryPlugin = {
                             }
                             text = textParts.join("\n");
                         }
-                        // Strip injected memory/tool blocks — keep the user's actual content
-                        text = text.replace(/<relevant-memories>[\s\S]*?<\/relevant-memories>/g, "").trim();
-                        text = text.replace(/<memory-tools>[\s\S]*?<\/memory-tools>/g, "").trim();
+                        // Strip envelope metadata and injected blocks — keep the user's actual content
+                        text = stripEnvelopeMetadata(text);
                         if (!text || text.length < 5)
                             continue;
                         const roleLabel = role === "user" ? "User" : "Assistant";
@@ -660,7 +809,7 @@ const rebacMemoryPlugin = {
                             }
                             return "";
                         };
-                        const userMsg = extractText(lastUserMsg);
+                        const userMsg = stripEnvelopeMetadata(extractText(lastUserMsg));
                         const assistantMsg = extractText(lastAssistMsg);
                         if (userMsg && assistantMsg) {
                             backend.enrichSession({
@@ -738,6 +887,21 @@ const rebacMemoryPlugin = {
                             api.logger.warn(`openclaw-memory-rebac: failed to write owner for agent:${agentId}: ${err}`);
                         }
                     }
+                    // Write group → owner relationships from groupOwners config
+                    for (const [groupId, ownerIds] of Object.entries(cfg.groupOwners)) {
+                        for (const ownerId of ownerIds) {
+                            try {
+                                const ownerSubject = { type: "person", id: ownerId };
+                                const token = await ensureGroupOwnership(spicedb, groupId, ownerSubject);
+                                if (token)
+                                    defaultState.lastWriteToken = token;
+                                api.logger.info(`openclaw-memory-rebac: set person:${ownerId} as owner of group:${groupId}`);
+                            }
+                            catch (err) {
+                                api.logger.warn(`openclaw-memory-rebac: failed to write owner for group:${groupId}: ${err}`);
+                            }
+                        }
+                    }
                 }
                 api.logger.info(`openclaw-memory-rebac: initialized (backend: ${backend.name} ${backendStatus.healthy ? "OK" : "UNREACHABLE"}, spicedb: ${spicedbOk ? "OK" : "UNREACHABLE"})`);
             },

package/docker/docker-compose.evermemos.yml

@@ -0,0 +1,21 @@
+###############################################################################
+# openclaw-memory-rebac — Combined stack (EverMemOS + SpiceDB)
+#
+# Brings up the full memory service stack with EverMemOS as the backend:
+#   - EverMemOS FastAPI server + MongoDB + Milvus + Elasticsearch + Redis
+#   - SpiceDB authorization engine + PostgreSQL
+#
+# Usage:
+#   cd docker/evermemos && cp .env.example .env  # configure API keys
+#   cd docker && docker compose -f docker-compose.evermemos.yml up -d
+#
+# EverMemOS endpoint:  http://localhost:1995
+# SpiceDB endpoint:    localhost:50051 (insecure)
+#
+# To use Graphiti instead:
+#   docker compose up -d              # uses docker-compose.yml (Graphiti + SpiceDB)
+###############################################################################
+
+include:
+  - path: ./spicedb/docker-compose.yml
+  - path: ./evermemos/docker-compose.yml

package/docker/{docker-compose.yml → docker-compose.graphiti.yml}

@@ -6,7 +6,7 @@
 #   - SpiceDB authorization engine + PostgreSQL
 #
 # Usage:
-#   docker compose up -d
+#   docker compose -f docker-compose.graphiti.yml up -d
 #
 # Graphiti endpoint:  http://localhost:8000
 # SpiceDB endpoint:   localhost:50051 (insecure)

package/docker/evermemos/.env.example

@@ -0,0 +1,85 @@
+# =============================================================================
+# EverMemOS Configuration
+# =============================================================================
+#
+# Copy this file to .env and fill in your API keys.
+# Database connection settings are pre-configured for Docker — no changes needed.
+#
+#   cp .env.example .env
+#
+# SECURITY: Never commit .env to version control.
+# =============================================================================
+
+
+# ===================
+# LLM Configuration (required)
+# ===================
+# Used for memory extraction (MemCell pipeline).
+
+LLM_PROVIDER=openai
+LLM_MODEL=gpt-4o-mini
+LLM_BASE_URL=https://api.openai.com/v1
+LLM_API_KEY=sk-your-key-here
+LLM_TEMPERATURE=0.3
+LLM_MAX_TOKENS=32768
+
+# Alternative: OpenRouter (uncomment and set key)
+# LLM_MODEL=x-ai/grok-4-fast
+# LLM_BASE_URL=https://openrouter.ai/api/v1
+# LLM_API_KEY=sk-or-v1-your-key-here
+
+
+# ===================
+# Vectorize / Embedding (required)
+# ===================
+# Used for semantic search. Supports vLLM (self-hosted) or DeepInfra (commercial).
+
+VECTORIZE_PROVIDER=deepinfra
+VECTORIZE_API_KEY=your-deepinfra-key-here
+VECTORIZE_BASE_URL=https://api.deepinfra.com/v1/openai
+VECTORIZE_MODEL=Qwen/Qwen3-Embedding-4B
+VECTORIZE_DIMENSIONS=1024
+VECTORIZE_TIMEOUT=30
+VECTORIZE_MAX_RETRIES=3
+VECTORIZE_BATCH_SIZE=10
+VECTORIZE_MAX_CONCURRENT=5
+VECTORIZE_ENCODING_FORMAT=float
+
+# Alternative: self-hosted vLLM (uncomment)
+# VECTORIZE_PROVIDER=vllm
+# VECTORIZE_API_KEY=EMPTY
+# VECTORIZE_BASE_URL=http://host.docker.internal:8000/v1
+
+# Optional: fallback vectorize provider
+# VECTORIZE_FALLBACK_PROVIDER=deepinfra
+# VECTORIZE_FALLBACK_API_KEY=your-fallback-key
+# VECTORIZE_FALLBACK_BASE_URL=https://api.deepinfra.com/v1/openai
+
+
+# ===================
+# Rerank (required)
+# ===================
+# Used for search result reranking. Supports vLLM or DeepInfra.
+
+RERANK_PROVIDER=deepinfra
+RERANK_API_KEY=your-deepinfra-key-here
+RERANK_BASE_URL=https://api.deepinfra.com/v1/inference
+RERANK_MODEL=Qwen/Qwen3-Reranker-4B
+RERANK_TIMEOUT=30
+RERANK_MAX_RETRIES=3
+RERANK_BATCH_SIZE=10
+RERANK_MAX_CONCURRENT=5
+
+# Optional: fallback rerank provider
+# RERANK_FALLBACK_PROVIDER=none
+# RERANK_FALLBACK_API_KEY=
+# RERANK_FALLBACK_BASE_URL=
+
+
+# ===================
+# Application Settings
+# ===================
+
+LOG_LEVEL=INFO
+ENV=dev
+MEMORY_LANGUAGE=en

package/docker/evermemos/Dockerfile

@@ -0,0 +1,133 @@
+###############################################################################
+# EverMemOS All-in-One Container
+#
+# Bundles all required services into a single container:
+#   - MongoDB 7.0      (port 27017)
+#   - Elasticsearch 8   (port 9200, internal only)
+#   - Milvus standalone (port 19530, with embedded etcd)
+#   - Redis 7           (port 6379, internal only)
+#   - EverMemOS API     (port 1995, exposed)
+#
+# Managed by supervisord. All data stored under /data.
+#
+# Pinned to EverMemOS commit SHA for reproducibility.
+# Update EVERMEMOS_COMMIT to upgrade.
+#
+# Build:
+#   docker compose build evermemos
+#
+# Override version at build time:
+#   docker compose build --build-arg EVERMEMOS_COMMIT=<sha> evermemos
+###############################################################################
+
+# Stage 1: Extract Milvus binaries from official image
+FROM milvusdb/milvus:v2.5.2 AS milvus-source
+
+# Stage 2: All-in-one container
+FROM ubuntu:22.04
+
+ARG EVERMEMOS_COMMIT=3c9a2d02460748310c7707048f7ed6b6bb078ab4
+ARG TARGETARCH
+
+ENV DEBIAN_FRONTEND=noninteractive
+
+# ---------------------------------------------------------------------------
+# Base packages + supervisord
+# ---------------------------------------------------------------------------
+RUN apt-get update && apt-get install -y --no-install-recommends \
+      supervisor curl wget gnupg git ca-certificates \
+      python3 python3-pip python3-venv \
+      redis-server \
+    && rm -rf /var/lib/apt/lists/*
+
+# ---------------------------------------------------------------------------
+# MongoDB 7.0
+# ---------------------------------------------------------------------------
+RUN curl -fsSL https://www.mongodb.org/static/pgp/server-7.0.asc | \
+      gpg --dearmor -o /usr/share/keyrings/mongodb-server-7.0.gpg && \
+    echo "deb [ signed-by=/usr/share/keyrings/mongodb-server-7.0.gpg ] \
+      https://repo.mongodb.org/apt/ubuntu jammy/mongodb-org/7.0 multiverse" \
+      > /etc/apt/sources.list.d/mongodb-org-7.0.list && \
+    apt-get update && \
+    apt-get install -y --no-install-recommends mongodb-org && \
+    rm -rf /var/lib/apt/lists/*
+
+# ---------------------------------------------------------------------------
+# Elasticsearch 8.11 (no security, single-node)
+# ---------------------------------------------------------------------------
+RUN curl -fsSL https://artifacts.elastic.co/GPG-KEY-elasticsearch | \
+      gpg --dearmor -o /usr/share/keyrings/elasticsearch.gpg && \
+    echo "deb [signed-by=/usr/share/keyrings/elasticsearch.gpg] \
+      https://artifacts.elastic.co/packages/8.x/apt stable main" \
+      > /etc/apt/sources.list.d/elasticsearch.list && \
+    apt-get update && \
+    apt-get install -y --no-install-recommends elasticsearch && \
+    rm -rf /var/lib/apt/lists/*
+
+# ES config: single-node, no security, limit heap
+RUN sed -i 's/xpack.security.enabled: true/xpack.security.enabled: false/' /etc/elasticsearch/elasticsearch.yml && \
+    sed -i '/cluster.initial_master_nodes/d' /etc/elasticsearch/elasticsearch.yml && \
+    echo "discovery.type: single-node" >> /etc/elasticsearch/elasticsearch.yml && \
+    echo "network.host: 127.0.0.1" >> /etc/elasticsearch/elasticsearch.yml && \
+    echo "-Xms512m" > /etc/elasticsearch/jvm.options.d/heap.options && \
+    echo "-Xmx512m" >> /etc/elasticsearch/jvm.options.d/heap.options
+
+# ---------------------------------------------------------------------------
+# Milvus standalone (copied from official Docker image)
+# ---------------------------------------------------------------------------
+COPY --from=milvus-source /milvus /opt/milvus
+RUN apt-get update && apt-get install -y --no-install-recommends \
+      libgomp1 libtbb2 libopenblas-dev libaio1 && \
+    rm -rf /var/lib/apt/lists/*
+
+# Milvus config for embedded etcd + local storage (no minio)
+RUN mkdir -p /data/milvus /opt/milvus/configs && \
+    printf '%s\n' \
+      'listen-client-urls: http://0.0.0.0:2379' \
+      'advertise-client-urls: http://0.0.0.0:2379' \
+      'quota-backend-bytes: 4294967296' \
+      'auto-compaction-mode: revision' \
+      "auto-compaction-retention: '1000'" \
+      > /opt/milvus/configs/embedEtcd.yaml
+
+ENV LD_LIBRARY_PATH=/opt/milvus/lib:$LD_LIBRARY_PATH
+ENV PATH=/opt/milvus/bin:$PATH
+
+# ---------------------------------------------------------------------------
+# EverMemOS (Python app from source)
+# ---------------------------------------------------------------------------
+RUN pip install --no-cache-dir uv
+
+WORKDIR /app
+RUN git clone https://github.com/EverMind-AI/EverMemOS.git . && \
+    git checkout "$EVERMEMOS_COMMIT" && \
+    uv sync --no-dev
+
+# ---------------------------------------------------------------------------
+# Data directories
+# ---------------------------------------------------------------------------
+RUN mkdir -p /data/mongodb /data/elasticsearch /data/milvus /data/redis
+
+# ---------------------------------------------------------------------------
+# Supervisord configuration
+# ---------------------------------------------------------------------------
+COPY supervisord.conf /etc/supervisor/conf.d/evermemos.conf
+COPY entrypoint.sh /entrypoint.sh
+RUN chmod +x /entrypoint.sh
+
+# ---------------------------------------------------------------------------
+# Trace overlay: read-only endpoint for message_id → derived memory ObjectIds
+# Same pattern as Graphiti's startup.py overlay — extends our image, not upstream.
+# ---------------------------------------------------------------------------
+COPY trace_overlay.py /app/trace_overlay.py
+RUN echo 'from trace_overlay import router as _trace_router; app.include_router(_trace_router)' >> /app/src/app.py
+
+# ---------------------------------------------------------------------------
+# Healthcheck — verify the EverMemOS API responds
+# ---------------------------------------------------------------------------
+HEALTHCHECK --interval=15s --timeout=10s --retries=10 --start-period=60s \
+  CMD curl -sf http://localhost:1995/health || exit 1
+
+EXPOSE 1995
+
+CMD ["/entrypoint.sh"]

package/docker/evermemos/docker-compose.yml

@@ -0,0 +1,52 @@
+###############################################################################
+# openclaw-memory-rebac — EverMemOS memory backend (all-in-one container)
+#
+# Single container bundles: MongoDB, Elasticsearch, Milvus, Redis, EverMemOS.
+# Managed by supervisord internally.
+#
+# Usage:
+#   cp .env.example .env          # configure LLM, vectorize, rerank API keys
+#   docker compose up -d          # builds image on first run (~5 min)
+#
+# EverMemOS endpoint:  http://localhost:1995
+#
+# Resource requirements: ~4 GB RAM (Elasticsearch + Milvus are memory-heavy)
+###############################################################################
+
+name: openclaw-evermemos
+
+services:
+  evermemos:
+    build:
+      context: .
+      args:
+        EVERMEMOS_COMMIT: 3c9a2d02460748310c7707048f7ed6b6bb078ab4
+    restart: unless-stopped
+    ports:
+      - "1995:1995"
+    env_file:
+      - .env
+    environment:
+      # All backing services run inside the container on localhost
+      MONGODB_HOST: 127.0.0.1
+      MONGODB_PORT: "27017"
+      MONGODB_USERNAME: ""
+      MONGODB_PASSWORD: ""
+      MONGODB_DATABASE: memsys
+      MONGODB_URI_PARAMS: "socketTimeoutMS=15000"
+      ES_HOSTS: http://127.0.0.1:9200
+      MILVUS_HOST: 127.0.0.1
+      MILVUS_PORT: "19530"
+      REDIS_HOST: 127.0.0.1
+      REDIS_PORT: "6379"
+    volumes:
+      - evermemos_data:/data
+    healthcheck:
+      test: ["CMD", "curl", "-sf", "http://localhost:1995/health"]
+      interval: 15s
+      timeout: 10s
+      retries: 10
+      start_period: 60s
+
+volumes:
+  evermemos_data:

package/docker/evermemos/trace_overlay.py

@@ -0,0 +1,128 @@
+"""
+Read-only tracing endpoint: message_id → derived memory ObjectIds.
+
+Mounted on the EverMemOS FastAPI app at startup via Dockerfile append.
+This is NOT a monkeypatch — it adds a new read-only endpoint to our Docker
+image, following the same pattern as the Graphiti startup.py overlay.
+
+Endpoint:
+    GET /api/v1/memories/trace/{message_id}
+
+Returns the MongoDB ObjectIds of all derived memories (episodic, foresight,
+event_log) produced from a given ingestion message. Used by the
+openclaw-memory-rebac plugin to write SpiceDB fragment relationships
+against the actual IDs that appear in search results.
+
+Response:
+    {
+        "message_id": "uuid-123",
+        "status": "complete|processing|not_found",
+        "memcell_ids": ["ObjectId-A"],
+        "derived_memories": {
+            "episodic_memory": ["ObjectId-B", ...],
+            "foresight": ["ObjectId-D", ...],
+            "event_log": ["ObjectId-E", ...],
+        },
+        "all_ids": ["ObjectId-B", "ObjectId-D", "ObjectId-E", ...]
+    }
+
+Uses pymongo (synchronous) since motor is not installed in EverMemOS.
+Blocking MongoDB calls are wrapped in asyncio.to_thread for FastAPI compat.
+"""
+
+import asyncio
+import os
+from pymongo import MongoClient
+from fastapi import APIRouter
+
+router = APIRouter(tags=["trace"])
+
+_db = None
+
+
+def _get_db():
+    global _db
+    if _db is None:
+        host = os.environ.get("MONGODB_HOST", "127.0.0.1")
+        port = os.environ.get("MONGODB_PORT", "27017")
+        username = os.environ.get("MONGODB_USERNAME", "")
+        password = os.environ.get("MONGODB_PASSWORD", "")
+        db_name = os.environ.get("MONGODB_DATABASE", "memsys")
+        if username and password:
+            mongo_uri = f"mongodb://{username}:{password}@{host}:{port}"
+        else:
+            mongo_uri = f"mongodb://{host}:{port}"
+        client = MongoClient(mongo_uri)
+        _db = client[db_name]
+    return _db
+
+
+def _trace_sync(message_id: str) -> dict:
+    """Synchronous MongoDB trace — run via asyncio.to_thread."""
+    db = _get_db()
+
+    # Step 1: Check if message_id exists in memory_request_logs
+    log_entry = db.memory_request_logs.find_one({"message_id": message_id})
+    if not log_entry:
+        return {
+            "message_id": message_id,
+            "status": "not_found",
+            "memcell_ids": [],
+            "derived_memories": {},
+            "all_ids": [],
+        }
+
+    # Step 2: Find memcell that contains this message_id in its original_data
+    # The message_id is stored at: original_data[*].messages[*].extend.message_id
+    memcell = db.memcells.find_one(
+        {"original_data.messages.extend.message_id": message_id}
+    )
+    if not memcell:
+        # Log exists but memcell not yet created — still in boundary detection
+        return {
+            "message_id": message_id,
+            "status": "processing",
+            "memcell_ids": [],
+            "derived_memories": {},
+            "all_ids": [],
+        }
+
+    memcell_id = str(memcell["_id"])
+
+    # Step 3: Query derived memory collections
+    derived = {
+        "episodic_memory": [],
+        "foresight": [],
+        "event_log": [],
+    }
+
+    for doc in db.episodic_memories.find(
+        {"memcell_event_id_list": memcell_id}, {"_id": 1}
+    ):
+        derived["episodic_memory"].append(str(doc["_id"]))
+
+    for doc in db.foresight_records.find(
+        {"parent_id": memcell_id, "parent_type": "memcell"}, {"_id": 1}
+    ):
+        derived["foresight"].append(str(doc["_id"]))
+
+    for doc in db.event_log_records.find(
+        {"parent_id": memcell_id, "parent_type": "memcell"}, {"_id": 1}
+    ):
+        derived["event_log"].append(str(doc["_id"]))
+
+    all_ids = [id_ for ids in derived.values() for id_ in ids]
+    status = "complete" if all_ids else "processing"
+
+    return {
+        "message_id": message_id,
+        "status": status,
+        "memcell_ids": [memcell_id],
+        "derived_memories": derived,
+        "all_ids": all_ids,
+    }
+
+
+@router.get("/api/v1/memories/trace/{message_id}")
+async def trace_message(message_id: str):
+    return await asyncio.to_thread(_trace_sync, message_id)