@contextableai/openclaw-memory-rebac 0.1.0

package/docker/graphiti/docker-compose.yml

@@ -0,0 +1,101 @@
+###############################################################################
+# openclaw-memory-rebac — Graphiti FastAPI REST server stack (standalone)
+#
+# Services:
+#   neo4j       — graph database
+#   graphiti    — Graphiti FastAPI REST server with extended config
+#
+# Usage:
+#   cp .env.example .env          # configure LLM, embedder, reranker
+#   docker compose up -d
+#
+# Graphiti endpoint:  http://graphiti:8000 (internal to Docker network only)
+#
+# LLM Configuration:
+#   Each AI component (LLM, embedder, reranker) can point to a different
+#   service. See .env for all available configuration options.
+###############################################################################
+
+name: openclaw-graphiti
+
+services:
+
+  # ---------------------------------------------------------------------------
+  # Neo4j — graph store for Graphiti
+  # ---------------------------------------------------------------------------
+  neo4j:
+    image: neo4j:5.26.2
+    restart: unless-stopped
+    expose:
+      - "7687"
+      - "7474"
+    environment:
+      NEO4J_AUTH: ${NEO4J_USER:-neo4j}/${NEO4J_PASSWORD:-graphiti_pw}
+    volumes:
+      - neo4j_data:/data
+    healthcheck:
+      test: ["CMD-SHELL", "wget -q --spider http://localhost:7474 || exit 1"]
+      interval: 10s
+      timeout: 10s
+      retries: 15
+      start_period: 30s
+
+  # ---------------------------------------------------------------------------
+  # Graphiti FastAPI REST server
+  # ---------------------------------------------------------------------------
+  graphiti:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    restart: unless-stopped
+    expose:
+      - "8000"
+    environment:
+      # -- Graph database (Neo4j) --
+      NEO4J_URI: bolt://neo4j:7687
+      NEO4J_USER: ${NEO4J_USER:-neo4j}
+      NEO4J_PASSWORD: ${NEO4J_PASSWORD:-graphiti_pw}
+
+      # -- Graphiti concurrency --
+      # build_indices_and_constraints fires 29 index queries concurrently
+      # (default semaphore limit = 20). Neo4j can't handle that many
+      # concurrent DDL ops and drops connections. Serialize them.
+      SEMAPHORE_LIMIT: 3
+
+      # -- LLM (entity extraction) --
+      OPENAI_API_KEY: ${LLM_API_KEY:?Set LLM_API_KEY in .env}
+      OPENAI_BASE_URL: ${LLM_BASE_URL:-}
+      MODEL_NAME: ${LLM_MODEL:-gpt-4o-mini}
+
+      # -- Embedder --
+      EMBEDDING_MODEL_NAME: ${EMBEDDING_MODEL:-text-embedding-3-small}
+      EMBEDDING_BASE_URL: ${EMBEDDING_BASE_URL:-}
+      EMBEDDING_API_KEY: ${EMBEDDING_API_KEY:-}
+      EMBEDDING_DIM: ${EMBEDDING_DIM:-}
+
+      # -- Reranker / cross-encoder --
+      # Default: "bge" runs BAAI/bge-reranker-v2-m3 locally (no API needed)
+      # Set to "openai" to use a remote reranker API instead
+      RERANKER_PROVIDER: ${RERANKER_PROVIDER:-bge}
+      RERANKER_MODEL: ${RERANKER_MODEL:-}
+      RERANKER_BASE_URL: ${RERANKER_BASE_URL:-}
+      RERANKER_API_KEY: ${RERANKER_API_KEY:-}
+
+      # -- Additional provider keys (optional) --
+      ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY:-}
+      GOOGLE_API_KEY: ${GOOGLE_API_KEY:-}
+      GROQ_API_KEY: ${GROQ_API_KEY:-}
+    depends_on:
+      neo4j:
+        condition: service_healthy
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
+    healthcheck:
+      test: ["CMD", "curl", "-sf", "http://localhost:8000/healthcheck"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+      start_period: 15s
+
+volumes:
+  neo4j_data:

package/docker/graphiti/graphiti_overlay.py

@@ -0,0 +1,141 @@
+"""
+Extended Graphiti initialization with per-component client configuration.
+
+Defines OpenClawGraphiti — a subclass of the base Graphiti class that:
+  1. Properly forwards all constructor params (embedder, cross_encoder)
+  2. Adds the CRUD methods the FastAPI routes require
+
+We bypass ZepGraphiti because its __init__ only forwards (uri, user,
+password, llm_client) to super(), silently dropping embedder and
+cross_encoder. This causes all embedding calls to use the hardcoded
+default model (text-embedding-3-small) instead of the configured one.
+"""
+
+import logging
+
+from graphiti_core import Graphiti
+from graphiti_core.edges import EntityEdge
+from graphiti_core.errors import (
+    EdgeNotFoundError,
+    GroupsEdgesNotFoundError,
+    NodeNotFoundError,
+)
+from graphiti_core.llm_client.config import LLMConfig
+from graphiti_core.llm_client.openai_generic_client import OpenAIGenericClient
+from graphiti_core.embedder.openai import OpenAIEmbedder, OpenAIEmbedderConfig
+from graphiti_core.nodes import EntityNode, EpisodicNode
+
+from fastapi import HTTPException
+
+from graph_service.config_overlay import ExtendedSettings
+
+logger = logging.getLogger(__name__)
+
+
+class OpenClawGraphiti(Graphiti):
+    """Graphiti subclass with server-specific CRUD methods.
+
+    Unlike ZepGraphiti, this properly forwards ALL constructor params
+    (including embedder and cross_encoder) to the base Graphiti class,
+    so they are wired into GraphitiClients at construction time.
+    """
+
+    async def get_entity_edge(self, uuid: str):
+        try:
+            edge = await EntityEdge.get_by_uuid(self.driver, uuid)
+            return edge
+        except EdgeNotFoundError as e:
+            raise HTTPException(status_code=404, detail=e.message) from e
+
+    async def delete_entity_edge(self, uuid: str):
+        try:
+            edge = await EntityEdge.get_by_uuid(self.driver, uuid)
+            await edge.delete(self.driver)
+        except EdgeNotFoundError as e:
+            raise HTTPException(status_code=404, detail=e.message) from e
+
+    async def delete_group(self, group_id: str):
+        try:
+            edges = await EntityEdge.get_by_group_ids(self.driver, [group_id])
+        except GroupsEdgesNotFoundError:
+            logger.warning(f"No edges found for group {group_id}")
+            edges = []
+
+        nodes = await EntityNode.get_by_group_ids(self.driver, [group_id])
+        episodes = await EpisodicNode.get_by_group_ids(self.driver, [group_id])
+
+        for edge in edges:
+            await edge.delete(self.driver)
+        for node in nodes:
+            await node.delete(self.driver)
+        for episode in episodes:
+            await episode.delete(self.driver)
+
+    async def delete_episodic_node(self, uuid: str):
+        try:
+            episode = await EpisodicNode.get_by_uuid(self.driver, uuid)
+            await episode.delete(self.driver)
+        except NodeNotFoundError as e:
+            raise HTTPException(status_code=404, detail=e.message) from e
+
+
+def _create_reranker(settings: ExtendedSettings, llm_client):
+    """Create the appropriate reranker based on RERANKER_PROVIDER."""
+    if settings.reranker_provider == "openai":
+        from graphiti_core.cross_encoder.openai_reranker_client import OpenAIRerankerClient
+
+        reranker_config = LLMConfig(
+            api_key=settings.reranker_api_key or settings.openai_api_key,
+            base_url=settings.reranker_base_url or settings.openai_base_url,
+        )
+        if settings.reranker_model:
+            reranker_config.model = settings.reranker_model
+        return OpenAIRerankerClient(client=llm_client, config=reranker_config)
+
+    # Default: BGE reranker (runs locally via sentence-transformers, no API needed)
+    from graphiti_core.cross_encoder.bge_reranker_client import BGERerankerClient
+
+    return BGERerankerClient()
+
+
+def create_graphiti(settings: ExtendedSettings) -> OpenClawGraphiti:
+    """Create an OpenClawGraphiti instance with per-component client configuration."""
+
+    # -- LLM client (entity extraction) --
+    llm_config = LLMConfig(
+        api_key=settings.openai_api_key,
+        base_url=settings.openai_base_url,
+    )
+    if settings.model_name:
+        llm_config.model = settings.model_name
+        llm_config.small_model = settings.model_name
+    llm_client = OpenAIGenericClient(config=llm_config)
+
+    # -- Embedder --
+    embedder_api_key = settings.embedding_api_key or settings.openai_api_key
+    embedder_base_url = settings.embedding_base_url or settings.openai_base_url
+    embedder_kwargs = {
+        "api_key": embedder_api_key,
+        "base_url": embedder_base_url,
+    }
+    if settings.embedding_model_name:
+        embedder_kwargs["embedding_model"] = settings.embedding_model_name
+    if settings.embedding_dim is not None:
+        embedder_kwargs["embedding_dim"] = settings.embedding_dim
+    embedder_config = OpenAIEmbedderConfig(**embedder_kwargs)
+    embedder = OpenAIEmbedder(config=embedder_config)
+
+    # -- Reranker / cross-encoder --
+    reranker = _create_reranker(settings, llm_client)
+
+    # -- Construct with all params forwarded to base Graphiti --
+    client = OpenClawGraphiti(
+        uri=settings.neo4j_uri,
+        user=settings.neo4j_user,
+        password=settings.neo4j_password,
+        llm_client=llm_client,
+        embedder=embedder,
+        cross_encoder=reranker,
+    )
+
+    return client

package/docker/graphiti/startup.py

@@ -0,0 +1,222 @@
+"""
+Custom startup that configures the Graphiti FastAPI server to use our
+extended per-component embedder/reranker settings before launching uvicorn.
+
+Uses FastAPI's app.dependency_overrides to replace get_graphiti —
+the proper mechanism that works with Annotated[..., Depends()] captures.
+"""
+
+import asyncio
+import importlib
+import logging
+
+from graph_service.config_overlay import ExtendedSettings
+from graph_service.graphiti_overlay import create_graphiti
+
+logger = logging.getLogger(__name__)
+
+MAX_RETRIES = 5
+RETRY_BASE_DELAY = 3  # seconds, doubles each retry
+
+
+def patch():
+    """
+    Override graph_service modules so the app uses ExtendedSettings
+    (with per-component embedder/reranker config) instead of the base
+    Settings class.
+    """
+    settings = ExtendedSettings()
+
+    # -- Patch Settings class on config module --
+    # The @lru_cache get_settings() does `return Settings()`.
+    # Replacing the class on the module + clearing cache makes it
+    # return our ExtendedSettings (which has all base fields plus extras).
+    config_mod = importlib.import_module("graph_service.config")
+    config_mod.Settings = ExtendedSettings
+    config_mod.get_settings.cache_clear()
+
+    # -- Create the singleton client ONCE (loads BGE reranker weights) --
+    # Used for both index initialization and per-request dependency injection.
+    # Upstream get_graphiti creates/closes a client per-request, but POST
+    # /messages queues background work via AsyncWorker that outlives the
+    # request scope.  A process-lifetime singleton avoids "Driver closed" errors.
+    singleton_client = create_graphiti(settings)
+
+    # -- Patch initialize_graphiti on upstream modules --
+    # main.py does `from graph_service.zep_graphiti import initialize_graphiti`
+    # creating a local binding we must also replace.
+    zep_mod = importlib.import_module("graph_service.zep_graphiti")
+
+    async def patched_initialize_graphiti(s=None):
+        """Initialize graph DB indices with retry for Neo4j readiness."""
+        for attempt in range(1, MAX_RETRIES + 1):
+            try:
+                await singleton_client.build_indices_and_constraints()
+                logger.info("Graph indices built successfully (attempt %d)", attempt)
+                return
+            except Exception as e:
+                logger.warning(
+                    "build_indices_and_constraints failed (attempt %d/%d): %s",
+                    attempt, MAX_RETRIES, e,
+                )
+                if attempt == MAX_RETRIES:
+                    logger.error("All %d attempts failed, giving up", MAX_RETRIES)
+                    raise
+                delay = RETRY_BASE_DELAY * (2 ** (attempt - 1))
+                logger.info("Retrying in %ds...", delay)
+                await asyncio.sleep(delay)
+
+    zep_mod.initialize_graphiti = patched_initialize_graphiti
+
+    main_mod = importlib.import_module("graph_service.main")
+    main_mod.initialize_graphiti = patched_initialize_graphiti
+
+    # -- Override get_graphiti via FastAPI dependency_overrides --
+    # This is the proper mechanism: app.dependency_overrides replaces
+    # the function that Depends(get_graphiti) captured at import time.
+    # We must import the app AFTER patching initialize_graphiti above
+    # (the app's lifespan calls initialize_graphiti on startup).
+    from graph_service.main import app
+
+    original_get_graphiti = zep_mod.get_graphiti
+
+    async def patched_get_graphiti(settings_dep=None):
+        """Yield the long-lived Graphiti client."""
+        yield singleton_client
+
+    app.dependency_overrides[original_get_graphiti] = patched_get_graphiti
+
+    # -- 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.
+    ingest_mod = importlib.import_module("graph_service.routers.ingest")
+
+    async def resilient_worker(self):
+        """Worker loop with exception logging and recovery."""
+        while True:
+            try:
+                job = await self.queue.get()
+                logger.info("AsyncWorker processing job (queue size: %d)", self.queue.qsize())
+                await job()
+            except asyncio.CancelledError:
+                break
+            except Exception:
+                logger.exception("AsyncWorker job failed")
+
+    ingest_mod.AsyncWorker.worker = resilient_worker
+
+    # -- Fix Neo4j CypherTypeError for nested attribute maps --
+    # graphiti-core does `entity_data.update(node.attributes or {})` for nodes
+    # and `edge_data.update(edge.attributes or {})` for edges, merging raw
+    # LLM-extracted attributes directly into Neo4j properties.
+    # Some LLMs (e.g., qwen2.5 via Ollama) return nested dicts/lists for
+    # attributes, which Neo4j rejects: "Property values can only be of
+    # primitive types."  Sanitize both entity nodes AND entity edges.
+    import json
+
+    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."""
+        if not attrs:
+            return attrs
+        sanitized = {}
+        for k, v in attrs.items():
+            if isinstance(v, (dict, list, set, tuple)):
+                sanitized[k] = json.dumps(v, default=str)
+            else:
+                sanitized[k] = v
+        return sanitized
+
+    async def patched_bulk_add(driver, episodic_nodes, episodic_edges,
+                                entity_nodes, entity_edges, embedder):
+        for node in entity_nodes:
+            if node.attributes:
+                node.attributes = _sanitize_attributes(node.attributes)
+        for edge in entity_edges:
+            if edge.attributes:
+                edge.attributes = _sanitize_attributes(edge.attributes)
+        return await original_bulk_add(
+            driver, episodic_nodes, episodic_edges,
+            entity_nodes, entity_edges, embedder,
+        )
+
+    bulk_mod.add_nodes_and_edges_bulk = patched_bulk_add
+
+    # Also patch the local binding in graphiti.py (uses `from ... import`)
+    graphiti_mod = importlib.import_module("graphiti_core.graphiti")
+    graphiti_mod.add_nodes_and_edges_bulk = patched_bulk_add
+
+    # -- Fix TypeError in extract_edges when LLM returns None for node indices --
+    # graphiti-core does `if not (-1 < source_idx < len(nodes) and -1 < target_idx < len(nodes))`
+    # which crashes with TypeError if the LLM returns None for an index.
+    #
+    # Primary fix: filter bad edges at model-parse level so valid edges from the same
+    # episode are preserved. Only applies when the Edge model has int fields (old
+    # index-based validation); a no-op for newer name-based validation.
+    # Fallback: catch TypeError from the whole function (loses all edges for that episode).
+    edge_ops_mod = importlib.import_module(
+        "graphiti_core.utils.maintenance.edge_operations"
+    )
+    original_extract_edges = edge_ops_mod.extract_edges
+
+    try:
+        _ep_mod = importlib.import_module("graphiti_core.prompts.extract_edges")
+        _OrigExtractedEdges = _ep_mod.ExtractedEdges
+        _OrigEdge = _ep_mod.Edge
+
+        # Collect Optional[int] fields (present in old index-based Edge model)
+        _int_fields = []
+        for _fname, _finfo in _OrigEdge.model_fields.items():
+            _ann = _finfo.annotation
+            if _ann is int:
+                _int_fields.append(_fname)
+            elif hasattr(_ann, "__args__") and int in _ann.__args__:
+                _int_fields.append(_fname)
+
+        if _int_fields:
+            _orig_mv = _OrigExtractedEdges.model_validate
+
+            @classmethod  # type: ignore[misc]
+            def _filtered_model_validate(cls, obj, *a, **kw):
+                result = _orig_mv.__func__(cls, obj, *a, **kw)
+                if result.edges:
+                    valid = [e for e in result.edges if all(getattr(e, f) is not None for f in _int_fields)]
+                    dropped = len(result.edges) - len(valid)
+                    if dropped:
+                        logger.warning("extract_edges: filtered %d edge(s) with None index fields", dropped)
+                    result.edges = valid
+                return result
+
+            _OrigExtractedEdges.model_validate = _filtered_model_validate
+            logger.info("Patched ExtractedEdges.model_validate to filter None int fields: %s", _int_fields)
+        else:
+            logger.info("ExtractedEdges uses name-based validation — None-index filter not needed")
+    except Exception as _patch_err:
+        logger.warning("Could not patch ExtractedEdges for None-index filtering: %s", _patch_err)
+
+    # Fallback: catch any remaining TypeError from the whole function
+    async def safe_extract_edges(*args, **kwargs):
+        try:
+            return await original_extract_edges(*args, **kwargs)
+        except TypeError as e:
+            if "not supported between instances" in str(e):
+                logger.warning("extract_edges skipped due to LLM output issue: %s", e)
+                return []
+            raise
+
+    edge_ops_mod.extract_edges = safe_extract_edges
+    # Patch the local binding in graphiti.py
+    graphiti_mod.extract_edges = safe_extract_edges
+
+    return app
+
+
+if __name__ == "__main__":
+    import uvicorn
+
+    app = patch()
+
+    port = ExtendedSettings().port
+    uvicorn.run(app, host="0.0.0.0", port=port)

package/docker/spicedb/docker-compose.yml

@@ -0,0 +1,79 @@
+###############################################################################
+# openclaw-memory-rebac — SpiceDB authorization stack (standalone)
+#
+# Services:
+#   postgres        — SpiceDB backing store (PostgreSQL 16)
+#   spicedb-migrate — one-shot schema migration
+#   spicedb         — authorization engine (gRPC :50051, HTTP :8080)
+#
+# Usage:
+#   cp .env.example .env          # set SPICEDB_PRESHARED_KEY
+#   docker compose up -d
+#
+# SpiceDB endpoint:   localhost:50051 (insecure by default)
+###############################################################################
+
+name: openclaw-spicedb
+
+services:
+
+  # ---------------------------------------------------------------------------
+  # PostgreSQL — SpiceDB backing store
+  # ---------------------------------------------------------------------------
+  postgres:
+    image: postgres:16-alpine
+    restart: unless-stopped
+    environment:
+      POSTGRES_USER: spicedb
+      POSTGRES_PASSWORD: ${SPICEDB_POSTGRES_PASSWORD:-spicedb}
+      POSTGRES_DB: spicedb
+    volumes:
+      - graphiti_spicedb_postgres_data:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U spicedb"]
+      interval: 5s
+      retries: 10
+
+  # ---------------------------------------------------------------------------
+  # SpiceDB migration (one-shot)
+  # ---------------------------------------------------------------------------
+  spicedb-migrate:
+    image: authzed/spicedb:latest
+    command: migrate head
+    environment:
+      SPICEDB_DATASTORE_ENGINE: postgres
+      SPICEDB_DATASTORE_CONN_URI: "postgres://spicedb:${SPICEDB_POSTGRES_PASSWORD:-spicedb}@postgres:5432/spicedb?sslmode=disable"
+    depends_on:
+      postgres:
+        condition: service_healthy
+    restart: "no"
+
+  # ---------------------------------------------------------------------------
+  # SpiceDB — authorization engine
+  # ---------------------------------------------------------------------------
+  spicedb:
+    image: authzed/spicedb:latest
+    command: serve
+    restart: unless-stopped
+    ports:
+      - "${SPICEDB_GRPC_PORT:-50051}:50051"   # gRPC
+      - "${SPICEDB_HTTP_PORT:-8080}:8080"      # HTTP metrics / healthz
+    environment:
+      SPICEDB_GRPC_PRESHARED_KEY: ${SPICEDB_PRESHARED_KEY:-dev_token}
+      SPICEDB_DATASTORE_ENGINE: postgres
+      SPICEDB_DATASTORE_CONN_URI: "postgres://spicedb:${SPICEDB_POSTGRES_PASSWORD:-spicedb}@postgres:5432/spicedb?sslmode=disable"
+      SPICEDB_GRPC_NO_TLS: "${SPICEDB_GRPC_NO_TLS:-true}"
+    depends_on:
+      spicedb-migrate:
+        condition: service_completed_successfully
+      postgres:
+        condition: service_healthy
+    healthcheck:
+      test: ["CMD", "grpc_health_probe", "-addr=localhost:50051"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+      start_period: 10s
+
+volumes:
+  graphiti_spicedb_postgres_data: