7.7 KiB

Raw Blame History

On-Premise Graph Memory

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.

Target architecture

MiroFish should not vendor or fork Graphiti. Graphiti stays an external service and is consumed through the graph-memory adapter layer.

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.

GRAPH_MEMORY_BACKEND=zep_cloud
ZEP_API_KEY=your_zep_api_key_here

On-premise mode is enabled explicitly:

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

The bridge receives the LLM credentials through the existing OpenAI-compatible variables:

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:

docker compose --profile graphiti up -d graphiti-falkordb graphiti-bridge

Then start or restart MiroFish:

docker compose build mirofish
docker compose up -d mirofish

For a full local stack, run:

docker compose --profile graphiti up -d

Expected runtime URLs

Inside Docker Compose:

MiroFish backend -> http://graphiti-bridge:8008
Graphiti bridge -> graphiti-falkordb:6379

From the host machine:

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:

curl http://127.0.0.1:8008/health

Check the MiroFish backend:

curl http://localhost:5001/health

Expected bridge response:

{
  "service": "graphiti-bridge",
  "status": "ok"
}

Smoke-test flow

After startup, verify the complete path through the application rather than only checking container health.

Open http://localhost:3000.
Create a new project.
Add a small but meaningful source document with several named actors and relationships.
Generate the ontology.
Build the graph.
Confirm that the graph contains more than placeholder nodes and edges.
Create a simulation.
Run at least one round.
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:

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:

Confirm Docker Desktop or Docker Engine is installed and running.
Clone the target MiroFish repository and checkout the on-premise graph-memory branch.
Create .env from .env.example.
Set GRAPH_MEMORY_BACKEND=graphiti_bridge.
Set GRAPHITI_BRIDGE_URL=http://graphiti-bridge:8008.
Set LLM_API_KEY, LLM_BASE_URL, and LLM_MODEL_NAME to an OpenAI-compatible model endpoint.
Set GRAPHITI_MODEL_NAME and GRAPHITI_EMBEDDING_MODEL_NAME if different from the defaults.
Start the stack with docker compose --profile graphiti up -d --build.
Verify http://127.0.0.1:8008/health returns status ok.
Verify http://localhost:5001/health returns successfully.
Open http://localhost:3000 and run a complete graph-build and simulation smoke test.
Inspect the graph result and reject the installation if only placeholder or generic nodes are created from a rich source document.
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.

7.7 KiB Raw Blame History