dbx-tools-graphiti

Native launcher for Graphiti with a local Neo4j backend. It runs both services directly as host processes; it does not use Docker, Podman, or another container runtime.

Install from PyPI:

uv add dbx-tools-graphiti

Or install the current main branch:

uv add "dbx-tools-graphiti @ git+https://github.com/reggie-db/dbx-tools.git@main#subdirectory=packages/py/graphiti"

Key features

• launches upstream Graphiti's HTTP MCP server at http://127.0.0.1:8000/mcp/;
• runs Neo4j Community 5.26 as a native background process;
• provisions Java 21 and uv through mise use -g only when absent;
• pins Graphiti and Neo4j versions for repeatable local environments;
• caches downloads, Python dependencies, Neo4j data, credentials, and logs;
• supports foreground or background operation without vendoring Graphiti code.

Quick start

mise must already be installed. The launcher handles Java and uv itself.

export OPENAI_API_KEY=...
uv run dbx-graphiti start

The first run downloads about 120 MB of Neo4j plus the pinned Graphiti release, creates Graphiti's uv environment, generates a local Neo4j password, starts Neo4j, and then runs Graphiti in the foreground. Later runs reuse all of it.

For background operation:

uv run dbx-graphiti up
uv run dbx-graphiti status
uv run dbx-graphiti down

Commands

Arguments after start or up are forwarded to upstream Graphiti. For example:

uv run dbx-graphiti start -- --port 9000 --group-id my-agent

Provisioning and caching

The package deliberately keeps orchestration separate from Graphiti itself:

1. It checks mise where java@21 and mise where uv@0.11.
2. A missing tool is installed globally with mise use -g --yes.
3. Neo4j Community 5.26.12 is downloaded from dist.neo4j.org and unpacked.
4. Graphiti v0.29.3 is downloaded from its GitHub release tag.
5. uv sync --project <checkout>/mcp_server creates the upstream environment.
6. A generated Neo4j password is stored with mode 0600 and supplied to Graphiti through its documented environment variables.

The cache root is:

• macOS: ~/Library/Application Support/dbx-tools/graphiti
• Linux: ${XDG_DATA_HOME:-~/.local/share}/dbx-tools/graphiti
• Windows: %LOCALAPPDATA%/dbx-tools/graphiti

Set DBX_GRAPHITI_HOME to override it. Removing the directory clears the download cache and permanently removes the local graph data.

Configuration

The packaged default fixes the database provider to Neo4j and otherwise follows upstream Graphiti environment names. Common settings are:

Explicit NEO4J_* values override generated defaults, which lets the Graphiti process use an existing Neo4j server. The launcher still manages its local Neo4j process; use upstream Graphiti directly if lifecycle ownership belongs to an external database administrator.

Graphiti owns MCP tools, graph behavior, LLM calls, embeddings, and migrations. This package owns only repeatable installation, configuration, and process lifecycle. See the upstream MCP server documentation for its complete API and provider configuration.