Graphiti

Full Graphiti stack — both halves of the upstream project, each running against its own graph database. Both application images are our own build, not upstream's — see "Our own fixed images" below for why and what's different.

All images are pinned to specific tags rather than :latest-style moving targets, so a docker compose pull won't silently change what's running: falkordb/falkordb:v4.20.1, itlostandfound/graphiti-mcp:1.0.2-fixed, neo4j:5.26.2, itlostandfound/graphiti-api:0.22.0-fixed. The version numbers in our tags match the exact upstream getzep/graphiti tags our fork's fixes are built on (mcp-v1.0.2 and v0.22.0 respectively) — chosen because those are what the last officially-published zepai/* images on Docker Hub actually were, confirmed by checking the registry directly rather than inferring from the publish workflow's logic (which turned out not to be reliable — see git history / commit messages on our fork for how that was discovered).

See Graphiti-Investigation-Report.md for the original background research. Two things in that report don't match the current upstream source (verified against getzep/graphiti directly): sentence_transformers isn't an embedder option the MCP server's EmbedderFactory actually supports, and the config key is providers.openai.api_url, not api_base. Both are handled correctly in config/config.yaml here.

Why two separate graph databases

The v0.22.0 source our graphiti-api build is based on has no FalkorDB support at all — not just "extra not installed": at that version (Oct 2025), server/graph_service/config.py doesn't even have a db_backend/falkordb_* field yet, and zep_graphiti.py constructs ZepGraphiti(uri=..., user=..., password=...) directly with no branching. FalkorDB support for the REST API was added later in getzep/graphiti's history (visible at git tag v0.29.2), but we built our fix on v0.22.0 specifically because that's what the last officially-published zepai/graphiti Docker Hub tag actually was — keeping our fork's baseline aligned with a known, previously-working reference point rather than jumping to newer upstream code we haven't run. Nothing stops you from rebasing the api-fixed branch on v0.29.2 later and adding real FalkorDB support to graphiti-api — it's your fork now — just hasn't been done here.

If you want them sharing a single FalkorDB graph, compose.yml has a commented-out graphiti-api-falkordb service that builds the REST API from a git context with INSTALL_FALKORDB=true — currently still pointed at upstream getzep/graphiti#v0.29.2, you'd want to repoint it at your own fork if you go this route.

Setup

1. Copy env.example.txt to .env. LLM/extraction calls go to Ollama Cloud (OLLAMA_BASE_URL=https://ollama.com/v1, needs a real OLLAMA_API_KEY from ollama.com — there's no local relay to fall back on anymore). Embeddings are kept local (LM Studio or similar) — fill in EMBEDDER_API_URL / EMBEDDER_MODEL once you've got a dedicated embedding model loaded and reachable from the Docker host. See "Embedder: local, not cloud" below for why and what to load.
2. Deploy behind Traefik:
   docker network create graphitinet # one-time, since compose.traefik.yml expects it external
   docker compose -f compose.traefik.yml up -d
3. Point your MCP clients at it — see "Connecting MCP clients" below.

Local testing (no Traefik)

docker compose up -d

Connecting MCP clients

Only graphiti-mcp is relevant here — graphiti-api is a plain REST API, not an MCP server. The MCP endpoint is https://${MCP_DOMAIN}/mcp/ behind Traefik, or http://localhost:8000/mcp/ for local testing via compose.yml. All three clients below support HTTP-transport MCP servers, just configured differently.

Hermes — add under mcp_servers in the profile's config.yaml:

mcp_servers:
  graphiti:
    url: "https://graphiti-mcp.whateveryouwant.com/mcp/"

Claude Code — either claude mcp add --transport http graphiti https://graphiti-mcp.whateveryouwant.com/mcp/, or add directly to .mcp.json in a project:

{
  "mcpServers": {
    "graphiti": {
      "type": "http",
      "url": "https://graphiti-mcp.whateveryouwant.com/mcp/"
    }
  }
}

Claude Desktop — check Settings for a "Custom Connector" / remote MCP server option first (recent versions support adding a URL directly, no bridge needed). If your version only supports local stdio servers, bridge through mcp-remote in claude_desktop_config.json instead:

{
  "mcpServers": {
    "graphiti": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://graphiti-mcp.whateveryouwant.com/mcp/"]
    }
  }
}

After connecting, verify with a round trip: call add_memory with some test text, then search_memory_facts or search_nodes and confirm it returns something — that exercises the full path (LLM extraction via Ollama Cloud → embedding via LM Studio → FalkorDB storage → retrieval) in one shot.

Endpoints exposed

Redis and Bolt aren't HTTP, so Traefik can't Host()-route them the way it does the four web UIs above — they're published directly on both compose files. Each has a commented-out Traefik TCP router block showing how to front it properly if you add a dedicated static entryPoint to ../1.traefik/data/traefik.yml (out of scope here since that's shared infra).

Embedder: local, not cloud

The LLM (chat/extraction) and embedder are configured as two separate OpenAI-compatible endpoints on purpose — llm points at Ollama Cloud, embedder points at a local server. Ollama Cloud's catalog is large chat/completion models (gpt-oss:120b, qwen3:235b, etc.); it's not really the place to host a small dedicated embedding model, and there's no cost/latency reason to send embedding calls over the network anyway.

Load a dedicated embedding model for EMBEDDER_MODEL — not a general chat model. A chat LLM (e.g. qwen3-8b) isn't trained for embeddings the way nomic-embed-text-v1.5 / bge-small-en-v1.5 / gte-small are (contrastive objective vs. next-token prediction) — even if a server like LM Studio can pool its hidden states into a vector on request, retrieval quality is typically worse than a purpose-built ~100-400M-param embedding model, despite being far heavier to run. Reserve a general chat model for the llm role if you ever want a local fallback to Ollama Cloud, not for embedder.

This deployment uses nomic-embed-text-v1.5 in LM Studio, under its real model identifier (EMBEDDER_MODEL=text-embedding-nomic-embed-text-v1.5@q8_0 by default — run lms ls if yours differs). No fake alias needed — see "Our own fixed images" below for why that used to be necessary and isn't anymore. Because it's a real catalog name now, ordinary LM Studio JIT load/unload is safe: leave it unloaded, let the first request load it, let it idle out after the TTL. You don't need to keep it pinned in memory or use lms load --identifier — that workaround was specifically needed because LM Studio's JIT loader has documented bugs around custom/aliased identifiers; a real catalog name doesn't hit that code path.

Our own fixed images

Four separate upstream bugs across three files in getzep/graphiti — none of them had any config-driven workaround, all of them were found by actually running this stack, not by reading the source in advance. Originally worked around by bind-mounting corrected copies of the affected files over the stock zepai/* images at container start; now fixed at the source instead, in a real fork: github.com/itlostandfound/graphiti-fixed, two branches (mcp-fixed off tag mcp-v1.0.2, api-fixed off tag v0.22.0 — matching the exact upstream versions the last officially-published Docker Hub images were built from), built into itlostandfound/graphiti-mcp:1.0.2-fixed and itlostandfound/graphiti-api:0.22.0-fixed and pushed to Docker Hub. Deploy server pulls pre-built images same as before — no code, no build step, no patches/ directory on it. If getzep/graphiti ever fixes these upstream, our fork's commits show exactly what to diff against to confirm, and the compose files can just point back at zepai/*.

1. MCP reranker → local, no API key. mcp_server/src/graphiti_mcp_server.py constructs Graphiti(...) twice (FalkorDB branch, Neo4j branch) and never passes cross_encoder= either time, so graphiti_core silently defaults to OpenAIRerankerClient() — hardcoded model gpt-4.1-nano, plus a logit_bias keyed to specific OpenAI-tokenizer token IDs that are meaningless against any other model's vocabulary (so unlike the embedder issue below, no Ollama Cloud/LM Studio substitute could ever work here even in principle — it would silently score relevance wrong, not just fail to connect).

Fix (fork commit on mcp-fixed): passes a local cross_encoder= to both Graphiti(...) calls instead of letting it default to OpenAI's. It tries graphiti_core's own BGERerankerClient (BAAI/bge-reranker-v2-m3 via sentence-transformers) first, since that's a real cross-encoder model, not a heuristic — the mcp_server Dockerfile's providers extra lists sentence-transformers as a dependency, so this should be available. It wasn't, in the actual published 1.0.2-standalone image (confirmed by the import failing at runtime — what a Dockerfile says it installs and what's actually in a published tag turned out not to be reliably the same thing twice in this project). So the fix falls back to a small dependency-free lexical-overlap reranker instead of crash-looping when that import fails — weaker than a real cross-encoder, but retrieval already went through semantic + BM25 + graph traversal before reranking runs, so this is a refinement pass, not the primary relevance signal. If sentence-transformers is ever actually present, BGERerankerClient is used automatically with no changes needed — the ./hf_cache volume is still mounted for that case.

2. DNS rebinding → disabled for proxied deployments. Confirmed as an actual upstream bug: getzep/graphiti#1205. FastMCP() is constructed at module level with no host= argument, so it defaults to "127.0.0.1" — and the SDK auto-enables DNS rebinding protection (Host header allowlist locked to 127.0.0.1/localhost/::1) whenever host is one of those at construction time. config.yaml's server.host: "0.0.0.0" is only applied after construction (mcp.settings.host = ..., further down the file), which doesn't retroactively fix the allowlist. Result: every request that arrives with a real Host header — i.e. anything routed through Traefik — gets rejected with 421 Invalid Host header, no matter what config.yaml says.

Fix (same fork commit as the reranker fix above, mcp-fixed branch): explicitly passes transport_security=TransportSecuritySettings(enable_dns_rebinding_protection=False) to the FastMCP(...) constructor. DNS rebinding protection defends a localhost-bound service against malicious-webpage-via-browser attacks — not the threat model for a server intentionally exposed through Traefik behind TLS, so disabling it outright is correct here rather than fighting the config-ordering bug.

3. LLM client → uses OLLAMA_BASE_URL, right API shape. mcp_server/src/services/factories.py's LLMClientFactory.create() has two separate bugs in its 'openai' case:

1. base_url is never read at all. EmbedderFactory.create() a few dozen lines below correctly does base_url=config.providers.openai.api_url — the LLM path is just missing the equivalent line entirely. Every LLM request silently went to real api.openai.com regardless of what OLLAMA_BASE_URL/config.yaml's api_url were set to, so it failed with 401 Incorrect API key provided — an Ollama Cloud key obviously isn't a valid OpenAI one, but you wouldn't know that from the error alone without checking which host the request actually went to.
2. Always uses OpenAIClient, which only works against real OpenAI. That class calls self.client.responses.parse(...) — OpenAI's newer Responses API (POST /v1/responses), which only OpenAI itself implements. OpenAIGenericClient is the class actually meant for this ("targets any OpenAI-compatible /chat/completions endpoint" per its own docstring) — even with base_url fixed, OpenAIClient would still fail against Ollama Cloud once the request reached the right host, just with a different error.

Fix (fork commit on mcp-fixed, mcp_server/src/services/factories.py): passes base_url through, and picks OpenAIClient only when api_url is unset or actually points at api.openai.com (preserving the reasoning/verbosity parameter support that class has for the gpt-5/o1/o3 family) — OpenAIGenericClient otherwise.

4. API embedder → wired up to real model name. server/graph_service/config.py defines an embedding_model_name field and server/graph_service/zep_graphiti.py's get_graphiti() applies the equivalent model_name field to the LLM client — but never applies embedding_model_name to the embedder at all. It's left on graphiti_core's bare OpenAIEmbedder() default: hardcoded model "text-embedding-3-small", connection falling through to the openai-python SDK's own OPENAI_API_KEY/OPENAI_BASE_URL env var fallback (which is why it happened to share the LLM's Ollama Cloud connection by accident before this was fixed, rather than reaching LM Studio at all).

Fix (fork commit on api-fixed, built on tag v0.22.0 specifically — this file's structure differs meaningfully from main/v0.29.2, no _create_graphiti_client() helper or FalkorDB branch exists yet at this version), two files:

• server/graph_service/config.py — adds embedder_api_url / embedder_api_key fields (separate from the LLM's openai_base_url/openai_api_key), and gives embedding_model_name a validation_alias='EMBEDDER_MODEL' so it reads the same env var graphiti-mcp already uses, instead of needing a second differently-named var for the same value.
• server/graph_service/zep_graphiti.py — applies those three fields to client.embedder.config in get_graphiti(), mirroring exactly what upstream already does for client.llm_client.config three lines above it.

No new env vars needed beyond what was already in .env for graphiti-mcp — both services now read EMBEDDER_API_URL/EMBEDDER_API_KEY/EMBEDDER_MODEL the same way, via the same shared .env.

Switching provider or backend

config/config.yaml (mounted over the MCP server's default) keeps the full upstream provider matrix — switch llm.provider / embedder.provider and set the matching env vars in .env to move off Ollama Cloud / your local embedder. The REST API's provider is controlled entirely through .env (OPENAI_API_KEY/OPENAI_BASE_URL/MODEL_NAME, mapped from the OLLAMA_* vars in the compose files' environment: blocks) since it has no mounted config file.

MCP server tools

add_memory, add_triplet, search_nodes, search_memory_facts, summarize_saga, build_communities, get_episode_entities, delete_entity_edge, delete_episode, get_entity_edge, get_episodes, clear_graph, get_status

Warnings

• Small/local LLMs frequently emit non-conforming JSON for entity/edge extraction — use the largest model your Ollama Cloud plan gives you access to.
• The REST API's embedder model name is hardcoded upstream to text-embedding-3-small with no override — fixed at the source in our fork rather than worked around, so EMBEDDER_MODEL is a real model name for both services now. See "Our own fixed images" above.
• FALKORDB_PASSWORD and NEO4J_PASSWORD ship with real, randomly-generated values in env.example.txt (auth is ON by default here, unlike upstream's own no-password default) — rotate them if this ever moves beyond a closed LAN, but don't blank FALKORDB_PASSWORD out without understanding the two-sided wiring: falkordb's REDIS_ARGS=--requirepass ${FALKORDB_PASSWORD} (in both compose files) is what makes the server enforce it, and graphiti-mcp reads the exact same var as the client password — same env var, both sides, by design, so they can't drift out of sync. A present-but-empty value (as opposed to the var being genuinely absent) is a real footgun either way: graphiti_mcp_server.py reads FALKORDB_PASSWORD via a raw os.environ.get(...) with no empty-string normalization (unlike config.yaml's ${FALKORDB_PASSWORD:} expansion, which does normalize), so an empty-but-present value makes the client send an empty-password AUTH — if the server isn't also configured to require one, that gets rejected outright and graphiti-mcp crash-loops with AUTH <password> called without any password configured for the default user.
• GRAPHITI_TELEMETRY_ENABLED=false is set by default in env.example.txt (opt-out PostHog telemetry on the MCP server, no data collection beyond system info). The REST API image doesn't expose an equivalent toggle.
• graphiti-mcp's search-result reranker is unconditionally OpenAI's upstream, with no config override point at all — fixed at the source in our fork to use graphiti_core's local BGERerankerClient. See "Our own fixed images" above. First startup downloads the ~2GB reranker model from HuggingFace Hub — expect a delay before the server reports ready the first time.
• Data does not migrate between FalkorDB and Neo4j — each is its own independent graph here, not a replica of the other.