From dabe89de267097fbb22cedc8123b2e273a8b556e Mon Sep 17 00:00:00 2001 From: Heiko Date: Mon, 15 Jun 2026 12:51:47 +0200 Subject: [PATCH] Document on-prem Graphiti deployment --- .env.example | 16 ++- README.md | 6 +- docs/on-prem-graph-memory.md | 198 ++++++++++++++++++++++++++++++++--- 3 files changed, 201 insertions(+), 19 deletions(-) diff --git a/.env.example b/.env.example index 78a3b72c..0491a501 100644 --- a/.env.example +++ b/.env.example @@ -5,12 +5,22 @@ LLM_API_KEY=your_api_key_here LLM_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1 LLM_MODEL_NAME=qwen-plus -# ===== ZEP记忆图谱配置 ===== -# 每月免费额度即可支撑简单使用：https://app.getzep.com/ +# ===== Graph memory backend ===== +# Default cloud mode: +GRAPH_MEMORY_BACKEND=zep_cloud + +# Zep Cloud configuration. Required only when GRAPH_MEMORY_BACKEND=zep_cloud. +# Free monthly quota is sufficient for simple usage: https://app.getzep.com/ ZEP_API_KEY=your_zep_api_key_here +# Local on-premise mode. Enable with: +# GRAPH_MEMORY_BACKEND=graphiti_bridge +# GRAPHITI_BRIDGE_URL=http://graphiti-bridge:8008 +# GRAPHITI_MODEL_NAME=gpt-5.4-mini +# GRAPHITI_EMBEDDING_MODEL_NAME=text-embedding-3-small + # ===== 加速 LLM 配置（可选）===== # 注意如果不使用加速配置，env文件中就不要出现下面的配置项 LLM_BOOST_API_KEY=your_api_key_here LLM_BOOST_BASE_URL=your_base_url_here -LLM_BOOST_MODEL_NAME=your_model_name_here \ No newline at end of file +LLM_BOOST_MODEL_NAME=your_model_name_here diff --git a/README.md b/README.md index de082935..8eef4db8 100644 --- a/README.md +++ b/README.md @@ -176,6 +176,10 @@ Reads `.env` from root directory by default, maps ports `3000 (frontend) / 5001 > Mirror address for faster pulling is provided as comments in `docker-compose.yml`, replace if needed. +### Optional: On-Premise Graph Memory + +The default graph-memory backend remains Zep Cloud. For local graph memory, MiroFish can run a Graphiti bridge and FalkorDB through Docker Compose. See [On-Premise Graph Memory](./docs/on-prem-graph-memory.md) for architecture, configuration, health checks, and installation-agent instructions. + ## 📬 Join the Conversation
@@ -200,4 +204,4 @@ MiroFish's simulation engine is powered by **[OASIS (Open Agent Social Interacti Star History Chart - \ No newline at end of file + diff --git a/docs/on-prem-graph-memory.md b/docs/on-prem-graph-memory.md index 7dc9d5d8..35fb3be1 100644 --- a/docs/on-prem-graph-memory.md +++ b/docs/on-prem-graph-memory.md @@ -1,23 +1,50 @@ # On-Premise Graph Memory -Mirofish now uses a graph-memory adapter layer. The default backend remains Zep Cloud, so existing behavior does not change unless the backend is explicitly switched. +This document describes the intended on-premise graph-memory setup for MiroFish. The goal is to keep the default Zep Cloud setup unchanged while allowing operators to run graph memory locally with Graphiti in a separate Docker service. -## Default: Zep Cloud +## Target architecture + +MiroFish should not vendor or fork Graphiti. Graphiti stays an external service and is consumed through the graph-memory adapter layer. + +```text +MiroFish application + -> graph-memory adapter + -> Zep Cloud adapter, default + -> Graphiti bridge adapter, optional on-premise mode + -> Graphiti bridge container + -> Graphiti Core from the public Graphiti package + -> FalkorDB container for graph storage +``` + +This separation keeps the MiroFish codebase small, avoids dependency conflicts with the existing backend, and makes the deployment model explicit. The Graphiti bridge container owns the Graphiti Python dependencies. MiroFish only calls the bridge through HTTP. + +## Repository responsibilities + +The MiroFish repository contains: + +- the graph-memory provider interface; +- the default Zep Cloud implementation; +- the optional Graphiti bridge implementation; +- the `graphiti_bridge` service wrapper; +- Docker Compose wiring for the bridge and FalkorDB; +- environment variables selecting the active backend. + +The MiroFish repository does not contain: + +- a copied Graphiti source tree; +- local modifications to the Graphiti upstream project; +- a hard dependency on on-premise graph memory for default users. + +## Backend selection + +Zep Cloud remains the default backend. Existing installations continue to work with the current configuration. ```env GRAPH_MEMORY_BACKEND=zep_cloud -ZEP_API_KEY=... +ZEP_API_KEY=your_zep_api_key_here ``` -## On-premise: Graphiti Bridge + FalkorDB - -Start the local graph-memory services: - -```bash -docker compose --profile graphiti up -d graphiti-falkordb graphiti-bridge -``` - -Switch Mirofish to the on-premise backend: +On-premise mode is enabled explicitly: ```env GRAPH_MEMORY_BACKEND=graphiti_bridge @@ -26,18 +53,159 @@ GRAPHITI_MODEL_NAME=gpt-5.4-mini GRAPHITI_EMBEDDING_MODEL_NAME=text-embedding-3-small ``` -Then rebuild/restart Mirofish: +The bridge receives the LLM credentials through the existing OpenAI-compatible variables: + +```env +LLM_API_KEY=your_api_key_here +LLM_BASE_URL=https://api.openai.com/v1 +LLM_MODEL_NAME=gpt-5.4-mini +``` + +## Docker services + +The on-premise graph-memory stack uses two additional services: + +| Service | Purpose | +| --- | --- | +| `graphiti-bridge` | HTTP compatibility layer used by MiroFish. It imports `graphiti-core` and translates MiroFish graph-memory calls to Graphiti operations. | +| `graphiti-falkordb` | Local graph database used by Graphiti. Data is persisted in the `graphiti_falkordb_data` Docker volume. | + +Start the graph-memory services with the `graphiti` profile: + +```bash +docker compose --profile graphiti up -d graphiti-falkordb graphiti-bridge +``` + +Then start or restart MiroFish: ```bash docker compose build mirofish docker compose up -d mirofish ``` -The Graphiti bridge runs in a separate container so its dependencies do not conflict with OASIS. FalkorDB data is stored in the `graphiti_falkordb_data` Docker volume. +For a full local stack, run: -Health checks: +```bash +docker compose --profile graphiti up -d +``` + +## Expected runtime URLs + +Inside Docker Compose: + +```text +MiroFish backend -> http://graphiti-bridge:8008 +Graphiti bridge -> graphiti-falkordb:6379 +``` + +From the host machine: + +```text +MiroFish frontend: http://localhost:3000 +MiroFish backend: http://localhost:5001 +Graphiti bridge: http://127.0.0.1:8008 +``` + +The bridge is bound to `127.0.0.1` on the host so it is not exposed on the network by default. + +## Health checks + +Check the bridge: ```bash curl http://127.0.0.1:8008/health +``` + +Check the MiroFish backend: + +```bash curl http://localhost:5001/health ``` + +Expected bridge response: + +```json +{ + "service": "graphiti-bridge", + "status": "ok" +} +``` + +## Smoke-test flow + +After startup, verify the complete path through the application rather than only checking container health. + +1. Open `http://localhost:3000`. +2. Create a new project. +3. Add a small but meaningful source document with several named actors and relationships. +4. Generate the ontology. +5. Build the graph. +6. Confirm that the graph contains more than placeholder nodes and edges. +7. Create a simulation. +8. Run at least one round. +9. Confirm that the simulation can read from graph memory and complete without a Zep Cloud key. + +For API-level validation, the same flow should cover ontology generation, graph build, simulation creation, simulation start, simulation status, graph readback, and report generation. + +## Operational notes + +- Use Zep Cloud for the default upstream-compatible mode. +- Use `graphiti_bridge` for local, no-cloud graph memory. +- Keep Graphiti isolated in its own container to avoid dependency conflicts. +- Keep the bridge API narrow and aligned with the MiroFish graph-memory adapter interface. +- Store graph data in the Docker volume `graphiti_falkordb_data`. +- Remove the volume only when local graph-memory data should be discarded. +- Do not expose the bridge port publicly unless an operator has added authentication and network controls. + +## Fresh MacBook installation notes + +For a clean on-premise installation on a new MacBook, the operator should install Docker Desktop, clone the MiroFish fork or the target branch, create `.env`, select `GRAPH_MEMORY_BACKEND=graphiti_bridge`, and start the Compose stack with the `graphiti` profile. + +The installation should not require a Zep Cloud account in on-premise mode. It still requires an OpenAI-compatible LLM endpoint because Graphiti extraction and embeddings use model calls. + +Recommended `.env` shape for on-premise testing: + +```env +LLM_API_KEY=your_api_key_here +LLM_BASE_URL=https://api.openai.com/v1 +LLM_MODEL_NAME=gpt-5.4-mini + +GRAPH_MEMORY_BACKEND=graphiti_bridge +GRAPHITI_BRIDGE_URL=http://graphiti-bridge:8008 +GRAPHITI_MODEL_NAME=gpt-5.4-mini +GRAPHITI_EMBEDDING_MODEL_NAME=text-embedding-3-small +``` + +## Instructions for an AI installation agent + +Use this section as the direct installation brief for an automated coding or operations agent. + +Objective: install and verify MiroFish with local on-premise graph memory. Do not use Zep Cloud. Do not copy Graphiti source code into MiroFish. Run Graphiti through the existing `graphiti_bridge` Docker service and persist graph data in FalkorDB. + +Steps: + +1. Confirm Docker Desktop or Docker Engine is installed and running. +2. Clone the target MiroFish repository and checkout the on-premise graph-memory branch. +3. Create `.env` from `.env.example`. +4. Set `GRAPH_MEMORY_BACKEND=graphiti_bridge`. +5. Set `GRAPHITI_BRIDGE_URL=http://graphiti-bridge:8008`. +6. Set `LLM_API_KEY`, `LLM_BASE_URL`, and `LLM_MODEL_NAME` to an OpenAI-compatible model endpoint. +7. Set `GRAPHITI_MODEL_NAME` and `GRAPHITI_EMBEDDING_MODEL_NAME` if different from the defaults. +8. Start the stack with `docker compose --profile graphiti up -d --build`. +9. Verify `http://127.0.0.1:8008/health` returns status `ok`. +10. Verify `http://localhost:5001/health` returns successfully. +11. Open `http://localhost:3000` and run a complete graph-build and simulation smoke test. +12. Inspect the graph result and reject the installation if only placeholder or generic nodes are created from a rich source document. +13. Record the tested commit, `.env` backend mode, container status, and smoke-test result. + +Acceptance criteria: + +- The application starts from Docker Compose. +- No Zep Cloud API key is required in `graphiti_bridge` mode. +- The bridge health check succeeds. +- A project can build a graph from source documents. +- Graph nodes and edges reflect the document content. +- A simulation can be created and started against the local graph memory. +- The setup remains compatible with the default Zep Cloud mode when `GRAPH_MEMORY_BACKEND=zep_cloud` is selected. + +Do not mark the installation complete if the graph build produces only a few generic nodes from a rich source document, if the simulation fails during startup, or if the application still requires `ZEP_API_KEY` while `GRAPH_MEMORY_BACKEND=graphiti_bridge` is selected.