@contextableai/openclaw-memory-rebac 0.1.0 → 0.1.2

package/dist/search.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Parallel Multi-Group Search + Merge/Re-rank
+ *
+ * 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.
+ */
+import type { MemoryBackend, SearchResult } from "./backend.js";
+export type { SearchResult };
+export type SearchOptions = {
+    query: string;
+    groupIds: string[];
+    limit?: number;
+    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).
+ */
+export declare function searchAuthorizedMemories(backend: MemoryBackend, options: SearchOptions): Promise<SearchResult[]>;
+/**
+ * Format search results into a text block for injecting into agent context.
+ */
+export declare function formatResultsForContext(results: SearchResult[]): string;
+/**
+ * Format results with long-term and session sections separated.
+ * 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

@@ -0,0 +1,98 @@
+/**
+ * Parallel Multi-Group Search + Merge/Re-rank
+ *
+ * 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.
+ */
+// ============================================================================
+// 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).
+ */
+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
+    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
+    const allResults = [];
+    for (const result of resultSets) {
+        if (result.status === "fulfilled") {
+            allResults.push(...result.value);
+        }
+    }
+    // Deduplicate by UUID
+    const seen = new Set();
+    const deduped = allResults.filter((r) => {
+        if (seen.has(r.uuid))
+            return false;
+        seen.add(r.uuid);
+        return true;
+    });
+    // Sort: score descending (when available), then recency descending
+    deduped.sort((a, b) => {
+        if (a.score !== undefined && b.score !== undefined && a.score !== b.score) {
+            return b.score - a.score;
+        }
+        const dateA = new Date(a.created_at).getTime();
+        const dateB = new Date(b.created_at).getTime();
+        return dateB - dateA;
+    });
+    return deduped.slice(0, limit);
+}
+// ============================================================================
+// Format for agent context
+// ============================================================================
+/**
+ * Format search results into a text block for injecting into agent context.
+ */
+export function formatResultsForContext(results) {
+    if (results.length === 0)
+        return "";
+    return results.map((r, i) => formatResultLine(r, i + 1)).join("\n");
+}
+/**
+ * Format results with long-term and session sections separated.
+ * Session group_ids start with "session-".
+ */
+export function formatDualResults(longTermResults, sessionResults) {
+    const parts = [];
+    let idx = 1;
+    for (const r of longTermResults) {
+        parts.push(formatResultLine(r, idx++));
+    }
+    if (sessionResults.length > 0) {
+        if (longTermResults.length > 0)
+            parts.push("Session memories:");
+        for (const r of sessionResults) {
+            parts.push(formatResultLine(r, idx++));
+        }
+    }
+    return parts.join("\n");
+}
+/**
+ * Format a single search result line with type-prefixed UUID.
+ * e.g. "[fact:da8650cb-...] Eric's birthday is Dec 17th (Eric -[HAS_BIRTHDAY]→ Dec 17th)"
+ */
+function formatResultLine(r, idx) {
+    const typeLabel = r.type === "node" ? "entity" :
+        r.type === "fact" ? "fact" :
+            r.type === "chunk" ? "chunk" :
+                r.type === "summary" ? "summary" :
+                    "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/dist/spicedb.d.ts

@@ -0,0 +1,80 @@
+/**
+ * SpiceDB Client Wrapper
+ *
+ * Wraps @authzed/authzed-node for authorization operations:
+ * WriteSchema, WriteRelationships, DeleteRelationships, BulkImportRelationships,
+ * LookupResources, CheckPermission.
+ */
+export type SpiceDbConfig = {
+    endpoint: string;
+    token: string;
+    insecure: boolean;
+};
+export type RelationshipTuple = {
+    resourceType: string;
+    resourceId: string;
+    relation: string;
+    subjectType: string;
+    subjectId: string;
+};
+export type ConsistencyMode = {
+    mode: "full";
+} | {
+    mode: "at_least_as_fresh";
+    token: string;
+} | {
+    mode: "minimize_latency";
+};
+export declare class SpiceDbClient {
+    private client;
+    private promises;
+    constructor(config: SpiceDbConfig);
+    writeSchema(schema: string): Promise<void>;
+    readSchema(): Promise<string>;
+    writeRelationships(tuples: RelationshipTuple[]): Promise<string | undefined>;
+    deleteRelationships(tuples: RelationshipTuple[]): Promise<void>;
+    deleteRelationshipsByFilter(params: {
+        resourceType: string;
+        resourceId: string;
+        relation?: string;
+    }): Promise<string | undefined>;
+    private toRelationship;
+    /**
+     * Bulk import relationships using the streaming ImportBulkRelationships RPC.
+     * More efficient than individual writeRelationships calls for large batches.
+     * Falls back to batched writeRelationships if the streaming RPC is unavailable.
+     */
+    bulkImportRelationships(tuples: RelationshipTuple[], batchSize?: number): Promise<number>;
+    private bulkImportViaStream;
+    private bulkImportViaWrite;
+    /**
+     * Read relationships matching a filter. Returns all tuples that match the
+     * specified resource type, optional resource ID, optional relation, and
+     * optional subject filter. Used by the cleanup command to find which
+     * Graphiti episodes have SpiceDB authorization relationships.
+     */
+    readRelationships(params: {
+        resourceType: string;
+        resourceId?: string;
+        relation?: string;
+        subjectType?: string;
+        subjectId?: string;
+        consistency?: ConsistencyMode;
+    }): Promise<RelationshipTuple[]>;
+    private buildConsistency;
+    checkPermission(params: {
+        resourceType: string;
+        resourceId: string;
+        permission: string;
+        subjectType: string;
+        subjectId: string;
+        consistency?: ConsistencyMode;
+    }): Promise<boolean>;
+    lookupResources(params: {
+        resourceType: string;
+        permission: string;
+        subjectType: string;
+        subjectId: string;
+        consistency?: ConsistencyMode;
+    }): Promise<string[]>;
+}

package/dist/spicedb.js

@@ -0,0 +1,267 @@
+/**
+ * SpiceDB Client Wrapper
+ *
+ * Wraps @authzed/authzed-node for authorization operations:
+ * WriteSchema, WriteRelationships, DeleteRelationships, BulkImportRelationships,
+ * LookupResources, CheckPermission.
+ */
+import { v1 } from "@authzed/authzed-node";
+// ============================================================================
+// Client
+// ============================================================================
+export class SpiceDbClient {
+    client;
+    promises;
+    constructor(config) {
+        if (config.insecure) {
+            this.client = v1.NewClient(config.token, config.endpoint, v1.ClientSecurity.INSECURE_PLAINTEXT_CREDENTIALS);
+        }
+        else {
+            this.client = v1.NewClient(config.token, config.endpoint);
+        }
+        this.promises = this.client.promises;
+    }
+    // --------------------------------------------------------------------------
+    // Schema
+    // --------------------------------------------------------------------------
+    async writeSchema(schema) {
+        const request = v1.WriteSchemaRequest.create({ schema });
+        await this.promises.writeSchema(request);
+    }
+    async readSchema() {
+        const request = v1.ReadSchemaRequest.create({});
+        const response = await this.promises.readSchema(request);
+        return response.schemaText;
+    }
+    // --------------------------------------------------------------------------
+    // Relationships
+    // --------------------------------------------------------------------------
+    async writeRelationships(tuples) {
+        const updates = tuples.map((t) => v1.RelationshipUpdate.create({
+            operation: v1.RelationshipUpdate_Operation.TOUCH,
+            relationship: v1.Relationship.create({
+                resource: v1.ObjectReference.create({
+                    objectType: t.resourceType,
+                    objectId: t.resourceId,
+                }),
+                relation: t.relation,
+                subject: v1.SubjectReference.create({
+                    object: v1.ObjectReference.create({
+                        objectType: t.subjectType,
+                        objectId: t.subjectId,
+                    }),
+                }),
+            }),
+        }));
+        const request = v1.WriteRelationshipsRequest.create({ updates });
+        const response = await this.promises.writeRelationships(request);
+        return response.writtenAt?.token;
+    }
+    async deleteRelationships(tuples) {
+        const updates = tuples.map((t) => v1.RelationshipUpdate.create({
+            operation: v1.RelationshipUpdate_Operation.DELETE,
+            relationship: v1.Relationship.create({
+                resource: v1.ObjectReference.create({
+                    objectType: t.resourceType,
+                    objectId: t.resourceId,
+                }),
+                relation: t.relation,
+                subject: v1.SubjectReference.create({
+                    object: v1.ObjectReference.create({
+                        objectType: t.subjectType,
+                        objectId: t.subjectId,
+                    }),
+                }),
+            }),
+        }));
+        const request = v1.WriteRelationshipsRequest.create({ updates });
+        await this.promises.writeRelationships(request);
+    }
+    async deleteRelationshipsByFilter(params) {
+        const request = v1.DeleteRelationshipsRequest.create({
+            relationshipFilter: v1.RelationshipFilter.create({
+                resourceType: params.resourceType,
+                optionalResourceId: params.resourceId,
+                ...(params.relation ? { optionalRelation: params.relation } : {}),
+            }),
+        });
+        const response = await this.promises.deleteRelationships(request);
+        return response.deletedAt?.token;
+    }
+    // --------------------------------------------------------------------------
+    // Bulk Import
+    // --------------------------------------------------------------------------
+    toRelationship(t) {
+        return v1.Relationship.create({
+            resource: v1.ObjectReference.create({
+                objectType: t.resourceType,
+                objectId: t.resourceId,
+            }),
+            relation: t.relation,
+            subject: v1.SubjectReference.create({
+                object: v1.ObjectReference.create({
+                    objectType: t.subjectType,
+                    objectId: t.subjectId,
+                }),
+            }),
+        });
+    }
+    /**
+     * Bulk import relationships using the streaming ImportBulkRelationships RPC.
+     * More efficient than individual writeRelationships calls for large batches.
+     * Falls back to batched writeRelationships if the streaming RPC is unavailable.
+     */
+    async bulkImportRelationships(tuples, batchSize = 1000) {
+        if (tuples.length === 0)
+            return 0;
+        // Try streaming bulk import first (uses CREATE semantics — rejects duplicates)
+        if (typeof this.promises.bulkImportRelationships === "function") {
+            try {
+                return await this.bulkImportViaStream(tuples, batchSize);
+            }
+            catch (err) {
+                // ALREADY_EXISTS means some relationships exist (e.g. partial previous run).
+                // Fall through to batched writeRelationships which uses TOUCH (idempotent).
+                const msg = err instanceof Error ? err.message : String(err);
+                if (msg.includes("ALREADY_EXISTS")) {
+                    return this.bulkImportViaWrite(tuples, batchSize);
+                }
+                throw err;
+            }
+        }
+        // Fallback: batched writeRelationships (uses TOUCH — idempotent)
+        return this.bulkImportViaWrite(tuples, batchSize);
+    }
+    bulkImportViaStream(tuples, batchSize) {
+        return new Promise((resolve, reject) => {
+            const stream = this.promises.bulkImportRelationships((err, response) => {
+                if (err)
+                    reject(err);
+                else
+                    resolve(Number(response?.numLoaded ?? tuples.length));
+            });
+            stream.on("error", (err) => {
+                reject(err);
+            });
+            for (let i = 0; i < tuples.length; i += batchSize) {
+                const chunk = tuples.slice(i, i + batchSize);
+                stream.write(v1.BulkImportRelationshipsRequest.create({
+                    relationships: chunk.map((t) => this.toRelationship(t)),
+                }));
+            }
+            stream.end();
+        });
+    }
+    async bulkImportViaWrite(tuples, batchSize) {
+        let total = 0;
+        for (let i = 0; i < tuples.length; i += batchSize) {
+            const chunk = tuples.slice(i, i + batchSize);
+            await this.writeRelationships(chunk);
+            total += chunk.length;
+        }
+        return total;
+    }
+    // --------------------------------------------------------------------------
+    // Read Relationships
+    // --------------------------------------------------------------------------
+    /**
+     * Read relationships matching a filter. Returns all tuples that match the
+     * specified resource type, optional resource ID, optional relation, and
+     * optional subject filter. Used by the cleanup command to find which
+     * Graphiti episodes have SpiceDB authorization relationships.
+     */
+    async readRelationships(params) {
+        const filterFields = {
+            resourceType: params.resourceType,
+        };
+        if (params.resourceId) {
+            filterFields.optionalResourceId = params.resourceId;
+        }
+        if (params.relation) {
+            filterFields.optionalRelation = params.relation;
+        }
+        if (params.subjectType) {
+            const subjectFilter = {
+                subjectType: params.subjectType,
+            };
+            if (params.subjectId) {
+                subjectFilter.optionalSubjectId = params.subjectId;
+            }
+            filterFields.optionalSubjectFilter = v1.SubjectFilter.create(subjectFilter);
+        }
+        const request = v1.ReadRelationshipsRequest.create({
+            relationshipFilter: v1.RelationshipFilter.create(filterFields),
+            consistency: this.buildConsistency(params.consistency),
+        });
+        const results = await this.promises.readRelationships(request);
+        const tuples = [];
+        for (const r of results) {
+            const rel = r.relationship;
+            if (!rel?.resource || !rel.subject?.object)
+                continue;
+            tuples.push({
+                resourceType: rel.resource.objectType,
+                resourceId: rel.resource.objectId,
+                relation: rel.relation,
+                subjectType: rel.subject.object.objectType,
+                subjectId: rel.subject.object.objectId,
+            });
+        }
+        return tuples;
+    }
+    // --------------------------------------------------------------------------
+    // Permissions
+    // --------------------------------------------------------------------------
+    buildConsistency(mode) {
+        if (!mode || mode.mode === "minimize_latency") {
+            return v1.Consistency.create({
+                requirement: { oneofKind: "minimizeLatency", minimizeLatency: true },
+            });
+        }
+        if (mode.mode === "at_least_as_fresh") {
+            return v1.Consistency.create({
+                requirement: {
+                    oneofKind: "atLeastAsFresh",
+                    atLeastAsFresh: v1.ZedToken.create({ token: mode.token }),
+                },
+            });
+        }
+        return v1.Consistency.create({
+            requirement: { oneofKind: "fullyConsistent", fullyConsistent: true },
+        });
+    }
+    async checkPermission(params) {
+        const request = v1.CheckPermissionRequest.create({
+            resource: v1.ObjectReference.create({
+                objectType: params.resourceType,
+                objectId: params.resourceId,
+            }),
+            permission: params.permission,
+            subject: v1.SubjectReference.create({
+                object: v1.ObjectReference.create({
+                    objectType: params.subjectType,
+                    objectId: params.subjectId,
+                }),
+            }),
+            consistency: this.buildConsistency(params.consistency),
+        });
+        const response = await this.promises.checkPermission(request);
+        return (response.permissionship ===
+            v1.CheckPermissionResponse_Permissionship.HAS_PERMISSION);
+    }
+    async lookupResources(params) {
+        const request = v1.LookupResourcesRequest.create({
+            resourceObjectType: params.resourceType,
+            permission: params.permission,
+            subject: v1.SubjectReference.create({
+                object: v1.ObjectReference.create({
+                    objectType: params.subjectType,
+                    objectId: params.subjectId,
+                }),
+            }),
+            consistency: this.buildConsistency(params.consistency),
+        });
+        const results = await this.promises.lookupResources(request);
+        return results.map((r) => r.resourceObjectId);
+    }
+}

package/docker/graphiti/.env

@@ -0,0 +1,50 @@
+# ============================================================================
+# Graphiti FastAPI REST server configuration
+# ============================================================================
+# Each AI component (LLM, embedder, reranker) can independently point to a
+# different service. If EMBEDDING_BASE_URL is not set, it defaults to
+# LLM_BASE_URL (or the OpenAI API if LLM_BASE_URL is also unset).
+
+# ============================================================================
+# LLM (entity extraction)
+# ============================================================================
+# Default: OpenAI API. Set LLM_BASE_URL to use a different provider:
+#   Ollama:   http://host.docker.internal:11434/v1
+#   vLLM:     http://your-vllm-server:8000/v1
+#   OpenAI:   (leave LLM_BASE_URL empty to use default)
+LLM_BASE_URL=http://100.123.48.104:11434/v1
+LLM_MODEL=qwen2.5:14b
+LLM_API_KEY=not-needed
+
+# ============================================================================
+# Embedder
+# ============================================================================
+# Default: OpenAI text-embedding-3-small.
+# If EMBEDDING_BASE_URL is empty, uses LLM_BASE_URL (or OpenAI default).
+EMBEDDING_MODEL=nomic-embed-text
+# EMBEDDING_BASE_URL=
+# EMBEDDING_API_KEY=
+EMBEDDING_DIM=768
+
+# ============================================================================
+# Reranker / cross-encoder
+# ============================================================================
+# Default: "bge" — runs BAAI/bge-reranker-v2-m3 locally via sentence-transformers.
+# No API key or external service needed. Fast, accurate, free.
+#
+# Set to "openai" to use a remote LLM-based reranker instead.
+RERANKER_PROVIDER=bge
+# RERANKER_MODEL=             # Only used when RERANKER_PROVIDER=openai
+# RERANKER_BASE_URL=          # Only used when RERANKER_PROVIDER=openai
+# RERANKER_API_KEY=           # Only used when RERANKER_PROVIDER=openai
+
+# ============================================================================
+# Neo4j
+# ============================================================================
+# NEO4J_USER=neo4j
+# NEO4J_PASSWORD=graphiti_pw
+
+# ============================================================================
+# Server
+# ============================================================================
+# GRAPHITI_PORT=8000

package/docker/graphiti/docker-compose.yml

@@ -48,8 +48,8 @@ services:
       context: .
       dockerfile: Dockerfile
     restart: unless-stopped
-    expose:
-      - "8000"
+    ports:
+      - "8000:8000"
     environment:
       # -- Graph database (Neo4j) --
       NEO4J_URI: bolt://neo4j:7687

package/docker/graphiti/graphiti_overlay.py

@@ -98,6 +98,31 @@ def _create_reranker(settings: ExtendedSettings, llm_client):
     return BGERerankerClient()
 
 
+class JsonSafeLLMClient(OpenAIGenericClient):
+    """Wrapper that ensures 'json' appears in messages when response_format is json_object.
+
+    Groq (and some other providers) require the word 'json' in the messages
+    when response_format={"type": "json_object"} is used. Graphiti's internal
+    prompts don't always include it, causing 400 errors.
+    """
+
+    async def _generate_response(self, messages, response_model=None, **kwargs):
+        # Check if any message already contains the word 'json' (case-insensitive)
+        has_json_mention = any('json' in m.content.lower() for m in messages)
+        if not has_json_mention:
+            # Inject into the first system message, or prepend one
+            injected = False
+            for m in messages:
+                if m.role == 'system':
+                    m.content += '\nRespond in JSON format.'
+                    injected = True
+                    break
+            if not injected:
+                from graphiti_core.prompts.models import Message
+                messages.insert(0, Message(role='system', content='Respond in JSON format.'))
+        return await super()._generate_response(messages, response_model, **kwargs)
+
+
 def create_graphiti(settings: ExtendedSettings) -> OpenClawGraphiti:
     """Create an OpenClawGraphiti instance with per-component client configuration."""
 
@@ -109,7 +134,7 @@ def create_graphiti(settings: ExtendedSettings) -> OpenClawGraphiti:
     if settings.model_name:
         llm_config.model = settings.model_name
         llm_config.small_model = settings.model_name
-    llm_client = OpenAIGenericClient(config=llm_config)
+    llm_client = JsonSafeLLMClient(config=llm_config)
 
     # -- Embedder --
     embedder_api_key = settings.embedding_api_key or settings.openai_api_key

package/docker/graphiti/startup.py

@@ -86,6 +86,26 @@ def patch():
 
     app.dependency_overrides[original_get_graphiti] = patched_get_graphiti
 
+    # -- Endpoint: entity edges extracted from a specific episode --
+    # graphiti-core stores an `episodes` list on each RELATES_TO relationship
+    # tracking which episodes contributed to that fact.  This endpoint exposes
+    # those UUIDs so the plugin can write per-fact SpiceDB relationships.
+    @app.get("/episodes/{episode_uuid}/edges")
+    async def get_episode_edges(episode_uuid: str):
+        """Return entity edge UUIDs that reference a specific episode."""
+        query = (
+            "MATCH ()-[r:RELATES_TO]-() "
+            "WHERE $episode_uuid IN r.episodes "
+            "RETURN DISTINCT r.uuid AS uuid"
+        )
+        # Use the raw Neo4j async driver directly to avoid differences
+        # in the Graphiti Neo4jDriver.execute_query() wrapper across versions.
+        raw_driver = singleton_client.driver.client
+        records, _, _ = await raw_driver.execute_query(
+            query, parameters_={"episode_uuid": episode_uuid}
+        )
+        return [{"uuid": r["uuid"]} for r in records]
+
     # -- Fix upstream AsyncWorker crash-on-error bug --
     # The worker loop only catches CancelledError; any other exception from
     # add_episode() kills the worker silently and no more jobs are processed.
@@ -117,12 +137,27 @@ def patch():
     bulk_mod = importlib.import_module("graphiti_core.utils.bulk_utils")
     original_bulk_add = bulk_mod.add_nodes_and_edges_bulk
 
-    def _sanitize_attributes(attrs):
-        """Flatten non-primitive attribute values to JSON strings for Neo4j."""
+    # Reserved keys that must not be overwritten by LLM-extracted attributes.
+    # See: https://github.com/contextablemark/openclaw-memory-rebac/issues/6
+    RESERVED_EDGE_KEYS = {
+        'uuid', 'source_node_uuid', 'target_node_uuid', 'name',
+        'fact', 'fact_embedding', 'group_id', 'episodes',
+        'created_at', 'expired_at', 'valid_at', 'invalid_at',
+    }
+    RESERVED_NODE_KEYS = {
+        'uuid', 'name', 'name_embedding', 'group_id', 'summary',
+        'created_at', 'labels',
+    }
+
+    def _sanitize_attributes(attrs, reserved_keys):
+        """Flatten non-primitive values and strip reserved keys to prevent clobber."""
         if not attrs:
             return attrs
         sanitized = {}
         for k, v in attrs.items():
+            if k in reserved_keys:
+                logger.debug("Stripped reserved key %r from attributes", k)
+                continue
             if isinstance(v, (dict, list, set, tuple)):
                 sanitized[k] = json.dumps(v, default=str)
             else:
@@ -133,10 +168,32 @@ def patch():
                                 entity_nodes, entity_edges, embedder):
         for node in entity_nodes:
             if node.attributes:
-                node.attributes = _sanitize_attributes(node.attributes)
+                node.attributes = _sanitize_attributes(node.attributes, RESERVED_NODE_KEYS)
         for edge in entity_edges:
+            # DIAGNOSTIC: log clobber attempts BEFORE stripping (so we can
+            # verify the fix is catching them).  Keep until confirmed in prod.
+            if edge.attributes and 'fact_embedding' in edge.attributes:
+                logger.warning(
+                    "DIAG attributes_clobber: edge=%s has 'fact_embedding' in attributes! "
+                    "value_type=%s (will be stripped)", edge.uuid,
+                    type(edge.attributes.get('fact_embedding')),
+                )
             if edge.attributes:
-                edge.attributes = _sanitize_attributes(edge.attributes)
+                edge.attributes = _sanitize_attributes(edge.attributes, RESERVED_EDGE_KEYS)
+            # DIAGNOSTIC: log edges with missing/invalid embeddings
+            emb = edge.fact_embedding
+            emb_ok = isinstance(emb, list) and len(emb) > 0 and all(isinstance(x, (int, float)) for x in emb[:5])
+            if not emb_ok:
+                logger.warning(
+                    "DIAG bad_embedding: edge=%s name=%r type=%s len=%s "
+                    "sample=%r fact=%r attrs_keys=%s src=%s tgt=%s",
+                    edge.uuid, edge.name,
+                    type(emb).__name__, len(emb) if isinstance(emb, (list, tuple)) else 'N/A',
+                    emb[:3] if isinstance(emb, list) else emb,
+                    edge.fact[:200] if edge.fact else None,
+                    list((edge.attributes or {}).keys()),
+                    edge.source_node_uuid, edge.target_node_uuid,
+                )
         return await original_bulk_add(
             driver, episodic_nodes, episodic_edges,
             entity_nodes, entity_edges, embedder,