Team Brain

A temporal knowledge graph that runs alongside the team server. Every linked editor inherits a graph_search MCP tool, searchable memory across every developer, every project, every session.

The flagship feature of v3.4. Run one command to spawn a Graphiti sidecar next to your team server. Every linked editor instantly inherits a graph_search MCP tool. The graph captures decisions, deploys, refactors, and incidents as temporal episodes that survive every chat window.

What it is

Graphiti is an open-source Python library that builds and queries temporal knowledge graphs from unstructured episodes, text, JSON, tool calls. It exposes itself as an MCP server, which means OpalServe can spawn it as a sidecar and any MCP-compatible client can query it.

OpalServe is already the control plane for your team's AI tools. Adding Graphiti makes it the team brain.

The defining trait of Graphiti is temporal, every relationship has a valid_at and invalid_at range. Queries can ask "what was true in March?" or "show me how the registry interface evolved" and get answers that respect chronology rather than overwriting old facts.

Enable it

opalserve enable graph

The wizard:

Detects Python 3.10+ across py, python3, and python (Windows-aware)
Asks you to pick an LLM provider, OpenAI, Anthropic, Ollama, or skip
Optionally pip install graphiti-core[kuzu] to your user site
Persists configuration to ~/.opalserve/graph/config.json

After enabling, opalserve start automatically spawns the Graphiti MCP server as a detached sidecar. The PID is tracked in ~/.opalserve/graph/sidecar.pid. Logs land in ~/.opalserve/graph/sidecar.log.

LLM providers

Graphiti requires an LLM for entity extraction during episode ingestion. OpalServe supports three providers:

Provider	Env var	Default model
OpenAI	`OPENAI_API_KEY`	`gpt-4o-mini`
Anthropic	`ANTHROPIC_API_KEY`	`claude-haiku-4-5-20251001`
Ollama	`OLLAMA_BASE_URL`	`llama3.2`

If you skip the provider during the wizard, the graph is still usable, you can add and search episodes, but ingestion of complex episodes will fall back to keyword extraction only.

Lifecycle

Once enabled, the sidecar follows the team server's lifecycle. Manual control is available when you need it:

opalserve graph status     # config + sidecar state + episode count
opalserve graph spawn      # manual restart (e.g. after editing config)
opalserve graph reset      # confirmation prompt → wipe data
opalserve disable graph    # stop sidecar, preserve data

opalserve doctor reports graph health, Python availability, graphiti-core import status, sidecar PID liveness, alongside the rest of its checks.

Adding episodes

Two paths:

Manual. Add a free-form decision or note from the CLI. Useful for capturing the why of a meeting.

opalserve graph add "We chose Drizzle ORM over Prisma for the new schema migration. Reason: tighter SQL control + better TS inference. Reviewed by Halsey and Vance on 2026-04-22."

Automatic. The auto-ingestion pipeline that feeds context docs and tool calls into the graph as episodes is on the roadmap. The graph is fully usable today via manual graph add and via the Graphiti MCP tools that linked editors inherit.

Querying the graph

Two paths here too:

From the CLI.

opalserve graph search "auth token decisions"

Returns the matching episodes with their citations and a flat view of the relevant subgraph.

From a linked editor. Once opalserve link --all has run, every editor has access to a graph_search MCP tool. Tell Claude or Cursor "search the team brain for the deploy on April 26" and it routes through OpalServe to the Graphiti sidecar and back.

The same hybrid search powers both paths: BM25 over the episode text, cosine similarity over the embeddings, and graph traversal over the temporal edges. All three combine into a single ranked result list.

Storage

The default backend is Kuzu, an embedded graph database. Zero infrastructure, the graph lives in ~/.opalserve/graph.kuzu as a single file. For team-scale deployments, FalkorDB and Neo4j are also supported via the backend field in ~/.opalserve/graph/config.json.

Backups are file-copies. Stop the team server, copy the .kuzu directory, restart. There is no online backup mode in v3.4.

Roadmap

Three things land in the next minor:

Auto-ingestion of context documents (opalserve context add → add_episode) and tool calls (every registry.callTool() → add_episode with tool name, args, result summary).
Per-user attribution, every episode tagged with the calling userId so the graph can answer per-person queries.
Privacy boundaries, opt-in episode redaction for sensitive tool args before they hit the graph.

The full architecture, including the eight implementation milestones, lives in docs/GRAPHITI_ARCHITECTURE.md on GitHub.

PreviousDocumentation NextHTTP API