`dbx-tools-graphiti`

Native launcher for Graphiti with local Neo4j and dbx-model-gateway processes configured for Databricks Model Serving. It runs directly on the host without 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;
starts dbx-model-gateway with an optional profile override, resolved local Databricks authentication, or ambient Databricks App authentication;
supervises Graphiti and the managed model gateway with Honcho so they share one lifecycle, receive SIGTERM as process groups, and receive SIGKILL after Honcho's bounded shutdown grace if needed;
journals attempted graph mutations to Postgres and reconstructs an ephemeral graph backend during startup;
defaults to databricks-gpt-5-nano and the 1024-dimensional databricks-gte-large-en embedding model;
reuses executables from PATH and installs missing Java 21, uv, Neo4j, and Graphiti source through mise;
pins Graphiti and Neo4j versions for repeatable local environments;
caches downloads, Python dependencies, Neo4j data, credentials, and logs;
needs no caller-owned config.yaml and does not vendor Graphiti code.

Quick start

Outside a Databricks App, configure a working Databricks CLI profile. A Databricks App uses its ambient service-principal authentication. The launcher installs mise when needed, handles Java, the model gateway, Graphiti, and Neo4j, and installs uv only when it is not already available:

uv run dbx-graphiti start

The launcher passes an explicit --profile to managed children. Without that flag, dbx-tools auth owns default profile and ambient App authentication.

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 the model gateway and Neo4j, and then runs Graphiti in the foreground. Later runs reuse the installed assets.

Honcho stops the sibling process when Graphiti or the managed model gateway exits. On Ctrl-C or SIGTERM it forwards SIGTERM to each child process group, waits up to five seconds, then sends SIGKILL to any remaining group. The launcher stops Neo4j after Honcho finishes.

For background operation:

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

Commands

start starts Neo4j, then runs Graphiti and the managed model gateway under Honcho in the foreground. Missing prerequisites are installed on demand. This is the default.
up starts all three services in the background.
down signals the Honcho supervisor, which stops Graphiti and the managed model gateway before the launcher stops Neo4j.
status prints process state, model selection, and the MCP URL as JSON.
env prints resolved database, proxy, and model settings as JSON. Its output includes the Neo4j password and must be treated as secret.

Arguments after -- are forwarded to upstream Graphiti:

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

Postgres persistence

DelegatingGraphDriver accepts any Graphiti GraphDriver and delegates its provider behavior, operations, sessions, transactions, search, and maintenance to that driver. Mutating Cypher statements are appended to a supplied ordered storage driver before the graph operation or transaction commits. During the first index setup, the wrapper clears the delegated graph and replays the stored mutations in order without journaling them again.

PostgresWriteStorage provides the durable implementation. It stores a namespaced append-only JSONB journal and accepts the async SQLAlchemy engine created by dbx-tools-postgres:

from dbx_tools.graphiti.persistence import (
    DelegatingGraphDriver,
    PostgresWriteStorage,
)
from dbx_tools.postgres.engine import create_async_engine, create_workspace_client

workspace = await create_workspace_client()
engine = create_async_engine(workspace, pool_pre_ping=True)
storage = PostgresWriteStorage(engine, namespace="memory-service")
driver = DelegatingGraphDriver(graph_driver, storage)

The bundled MCP launcher enables this automatically when any of these settings is present:

JOURNAL_DATABASE_URL: explicit PostgreSQL URL. The launcher uses asyncpg.
PGHOST, LAKEBASE_ENDPOINT, or LAKEBASE_INSTANCE_NAME: resolve the connection and rotating credential through dbx-tools-postgres and WorkspaceClient.
JOURNAL_NAMESPACE: isolates one journal within the table. The launcher derives a stable value from its data directory when omitted. A direct dbx_tools.graphiti.server invocation must set it explicitly.
JOURNAL_TABLE: journal table name. Defaults to dbx_tools_graphiti.graphiti_write_journal. A schema-qualified table causes the journal to create that schema when absent, avoiding Lakebase deployments where the application identity cannot write to public.

When persistence is configured, Postgres initialization or replay failure stops server startup rather than running without durability. The contract is write-ahead attempt recovery with ordered, at-least-once replay:

a direct write is appended before the delegated mutation;
a transaction callback is buffered as one journal append before the delegate commits, so a later commit failure retains that attempted batch;
a driver retry invokes the callback again and records another attempt;
replay runs entries in sequence after clearing the ephemeral graph and stops on the first invalid entry. Nothing is skipped or marked complete, so a later startup retries the same entry;
transaction batch boundaries are atomic in Postgres at append time but are not retained as replay groups. Replay executes each statement in sequence;
clone() and with_database() represent another view of the same logical graph and share the journal without taking storage ownership. Independent graphs require distinct storage namespaces;
the journal is append-only and has no checkpoint, retention, or compaction policy. Deleting old entries without an external full snapshot makes replay incomplete.

The journal is restart recovery for one live graph instance. It does not replicate new writes into other concurrently running Graphiti instances. A process crash after the graph write-ahead append but before the graph commit can leave an unacknowledged mutation in the journal. Graphiti's UUID-backed mutation queries are compatible with this replay model, but a custom delegate or write predicate must supply replay-safe mutations. Non-idempotent writes can be applied more than once and are outside this contract. If the local Neo4j credential no longer matches its ephemeral data directory, the launcher resets that directory only when a Postgres journal is configured, then Graphiti rebuilds it from the journal. Without durable storage, an authentication mismatch fails startup rather than deleting local graph data.

Provisioning and caching

The package deliberately keeps orchestration separate from Graphiti itself:

dbx_tools.core.bin checks PATH before asking mise for a tool.
When mise is missing on macOS or Linux, the official checksum-verifying installer runs under a cross-process lock.
Missing tools are installed globally with mise use -g --yes, then resolved with mise which or mise where.
Java 21, uv 0.11, and Neo4j Community 5.26.12 use their mise registry backends.
Graphiti 0.29.3 uses mise's HTTP backend against the pinned release source archive because the GitHub release has no platform binary asset.
uv sync --python <launcher-minor> --project <checkout>/mcp_server creates the upstream environment on the same Python minor as the launcher (or UV_PYTHON when set). The Graphiti child imports this package from the launcher PYTHONPATH, including the workspace roots for dbx_tools.postgres, so a looser upstream requires-python must not select a different interpreter.
A generated Neo4j password is stored with mode 0600.
The TypeScript AppKit model gateway starts against the selected Databricks profile, and Graphiti receives its OpenAI-compatible URL and model settings through environment variables and CLI flags.

The launcher is supported on macOS and Linux. The cache root is:

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

Set DBX_GRAPHITI_HOME to override it. The directory contains links to the mise-managed tools plus launcher state, logs, and Neo4j data. Removing it permanently removes the local graph data; mise manages its own download cache and installation directories separately.

Configuration

Callers do not supply a Graphiti config.yaml. The server creates an empty temporary YAML file for the lifetime of the upstream process because upstream requires the argument. Model and server settings resolve from CLI option, environment variable, then package default:

--profile: an optional explicit Databricks profile override. When absent, dbx-tools auth resolves the active Databricks identity.
--model / MODEL_NAME: defaults to databricks-gpt-5-nano.
--embedder-model / EMBEDDER_MODEL: defaults to databricks-gte-large-en.
--embedder-dimensions / EMBEDDER_DIMENSIONS: defaults to 1024.
--model-gateway-host / MODEL_GATEWAY_HOST: defaults to 127.0.0.1.
--model-gateway-port / MODEL_GATEWAY_PORT: defaults to 4400.
--model-gateway-url / MODEL_GATEWAY_URL: selects an external OpenAI-compatible endpoint.
--manage-model-gateway, --no-manage-model-gateway / MANAGE_MODEL_GATEWAY: explicitly controls whether the launcher owns the gateway.
MODEL_GATEWAY_COMMAND: executable and arguments used for managed mode.
LLM_STRUCTURED_OUTPUT_MODE: defaults to json_object.
GRAPHITI_GROUP_ID: defaults upstream to main.
GRAPHITI_HOST and GRAPHITI_PORT: environment-only listener settings. Without a port, the launcher uses DATABRICKS_APP_PORT when present and 8000 otherwise. Without a host, it binds 0.0.0.0 in a Databricks App and 127.0.0.1 elsewhere. The AppKit plugin selects a loopback endpoint for both.
NEO4J_URI and NEO4J_DATABASE: default to bolt://127.0.0.1:7687 and neo4j.

The launcher sets Graphiti's OpenAI provider and embedding dimensions directly. No OpenAI key is required for its managed local proxy.

To use a separately managed OpenAI-compatible proxy:

uv run dbx-graphiti start \
  --model-gateway-url https://models.example/v1 \
  --no-manage-model-gateway

Setting MODEL_GATEWAY_URL also selects external mode automatically. A direct OPENAI_API_URL selects external OpenAI-compatible mode and requires OPENAI_API_KEY. --manage-model-gateway overrides either environment choice when the launcher should still own the local gateway.

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 repeatable installation, Databricks defaults, and process lifecycle. To run it beside an AppKit server through one Databricks App port, use @dbx-tools/appkit-graphiti. See the upstream MCP server documentation for its complete API.

Modules

cli: Cyclopts commands and CLI-over-environment option binding;
settings: model, embedding, profile, and model-gateway resolution;
runtime: on-demand provisioning and Honcho lifecycle;
server: upstream MCP entry point, temporary config, and persistence wiring;
proxy: loopback Caddy process used by the AppKit plugin;
persistence: delegating graph driver and Postgres write-ahead journal;
supervisor: detached up entry point.

Metadata

Release files for dbx-tools-graphiti 0.9.38

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for dbx-tools-graphiti 0.9.38
File	Size	Uploaded
dbx_tools_graphiti-0.9.38.tar.gz	25.4 kB	Oct 6, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for dbx-tools-graphiti 0.9.38
File	Interpreter	ABI	Platform	Reset
dbx_tools_graphiti-0.9.38-py3-none-any.whl 30.6 kB Oct 6, 2026	Python 3	none	any	Details

Total release size: 55.9 kB

Release files / dbx_tools_graphiti-0.9.38.tar.gz

Download URL	dbx_tools_graphiti-0.9.38.tar.gz
Size	25.4 kB
Tags	Source
SHA-256 checksum How to use checksums	`79adf3f2ce951232bb541a22b3eefbc29ffc3e37abf35fd66d5923b15b1daf89`
BLAKE2b-256 checksum How to use checksums	`c6af8285522a34147186c5a300a196048b6c9f00cb3b3b8c6c30397ce9129674`
Upload date	Oct 6, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/reggie-db/dbx-tools
Publishing commit: github.com/reggie-db/dbx-tools/tree/998421e92776c476483eb6e80abda2a615810e92

Workflow

Publishing configuration: github.com/reggie-db/dbx-tools/blob/998421e92776c476483eb6e80abda2a615810e92/.github/workflows/release.yml
Publishing logs: github.com/reggie-db/dbx-tools/actions/runs/37395740902/attempts/1

Artifact

Subject: dbx_tools_graphiti-0.9.38.tar.gz
SHA-256 checksum: 79adf3f2ce951232bb541a22b3eefbc29ffc3e37abf35fd66d5923b15b1daf89 Verifying attestations

Release files / dbx_tools_graphiti-0.9.38-py3-none-any.whl

Download URL	dbx_tools_graphiti-0.9.38-py3-none-any.whl
Size	30.6 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`d1730b1fc6fa0f7afa3ff1ae73ebe0405fd38b71a05795f74004fef5c7d29a33`
BLAKE2b-256 checksum How to use checksums	`d2e19c80173e4d425ef9f8e9ac9112f0ab1f0453a9432b7ee9ad9b034b9bc182`
Upload date	Oct 6, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/reggie-db/dbx-tools
Publishing commit: github.com/reggie-db/dbx-tools/tree/998421e92776c476483eb6e80abda2a615810e92

Workflow

Publishing configuration: github.com/reggie-db/dbx-tools/blob/998421e92776c476483eb6e80abda2a615810e92/.github/workflows/release.yml
Publishing logs: github.com/reggie-db/dbx-tools/actions/runs/37395740902/attempts/1

Artifact

Subject: dbx_tools_graphiti-0.9.38-py3-none-any.whl
SHA-256 checksum: d1730b1fc6fa0f7afa3ff1ae73ebe0405fd38b71a05795f74004fef5c7d29a33 Verifying attestations