dbx-tools-graphiti Skill 技能

技能简介

dbx-tools-graphiti 是一款面向 Databricks Model Serving 的"开箱即用"Graphiti MCP 启动器——它把流行的开源实时知识图谱框架 Graphiti（31k+ GitHub Stars）与本地 Neo4j 5.26、dbx-model-proxy 一起打包成一条命令即可拉起的进程组，全程无需 Docker / Podman / 任何容器运行时。所有进程通过 Honcho 进程组管理，共享同一个生命周期；写操作走 Postgres write-ahead journal，启动时按序重放，保证持久性与可重建性。专为 Databricks 用户设计：默认使用 databricks-gpt-5-nano 与 1024 维 databricks-gte-large-en 嵌入模型，Databricks App 部署下自动用 ambient service-principal 鉴权，本地开发则走 Databricks CLI profile。

核心能力

• 零容器启动：原生进程方式拉起 Graphiti HTTP MCP（http://127.0.0.1:8000/mcp/）+ Neo4j 5.26 + dbx-model-proxy，没有 docker daemon 依赖
• Honcho 进程组治理：Graphiti 与 model proxy 共享一个 lifecycle，SIGTERM 广播到进程组，5 秒宽限后 SIGKILL 兜底，干净退出
• Postgres 写前日志（write-ahead journal）：所有 Cypher 变更先 append 到命名空间 JSONB，启动时按序回放重建临时图后端，保证 at-least-once 语义
• Databricks 原生集成：默认 databricks-gpt-5-nano + databricks-gte-large-en 嵌入；支持 --profile / DATABRICKS_CONFIG_PROFILE / Databricks App ambient 鉴权三种模式
• 缺失依赖自动补齐：复用 PATH 已有可执行，通过 mise 按需安装 Java 21、uv、Neo4j、Graphiti 源码
• 版本钉死：Graphiti 与 Neo4j 版本 pin 住，本地环境可重复；缓存下载、Python 依赖、Neo4j 数据、凭据、日志
• 无 caller-owned config：内置合理默认，外部 Databricks 鉴权之外不需要任何 config.yaml，不 vendoring Graphiti 源码
• MCP 标准输出：最终暴露的是上游 Graphiti 的 HTTP MCP 端点，任何 MCP 兼容 Agent（Claude Code / Cursor / Continue / 自研）零改造接入
• 生产级 supervisor：start（前台）/ up（后台守护）/ status（JSON 输出进程状态与 MCP URL）/ down（优雅停服）四件套

安装配置

1. PyPI 安装：uv add dbx-tools-graphiti（推荐 uv；pip 也可：pip install dbx-tools-graphiti）
2. 从 main 分支安装：uv add "dbx-tools-graphiti @ git+https://github.com/reggie-db/dbx-tools.git@main#subdirectory=packages/py/graphiti"
3. Databricks 鉴权（任选其一）：
   • 本地开发：配置好 databricks configure --profile
   • CI / 共享环境：export DATABRICKS_CONFIG_PROFILE=
   • Databricks App 部署：使用 ambient service-principal 鉴权，无需任何配置
4. 首次启动：uv run dbx-graphiti start，自动下载约 120MB Neo4j + Graphiti、生成 Neo4j 密码、拉起 model proxy + Neo4j + Graphiti
5. 后台运行：uv run dbx-graphiti up，后续用 status / down 管理
6. 持久化配置（可选）：设置 JOURNAL_DATABASE_URL 或 PGHOST / LAKEBASE_ENDPOINT / LAKEBASE_INSTANCE_NAME 启用 Postgres 写前日志；JOURNAL_NAMESPACE 用于多租户隔离；JOURNAL_TABLE 可指定 schema 前缀的表名
7. 透传参数：所有 -- 之后的参数转发给上游 Graphiti，例如 uv run dbx-graphiti start -- --port 9000 --group-id my-agent

使用步骤

1. 首次前台启动：uv run dbx-graphiti start，确认 Neo4j + Graphiti + dbx-model-proxy 都拉起，访问 http://127.0.0.1:8000/mcp/ 验证 MCP 端点
2. 查看状态：uv run dbx-graphiti status 输出 JSON（进程 PID、模型选择、MCP URL），便于脚本化集成
3. 让 Claude Code / Cursor 接入：在 Agent 的 MCP 配置里加 {"type":"http","url":"http://127.0.0.1:8000/mcp/"}，重启 Agent
4. 后台守护：uv run dbx-graphiti up 启动后台三件套，工作期间持续提供服务
5. 写操作：让 Agent 通过 MCP 工具调用 Cypher 变更，所有 mutation 自动 journal 到 Postgres
6. 优雅停服：uv run dbx-graphiti down，Honcho 给所有进程组发 SIGTERM，5 秒后 SIGKILL 兜底；Neo4j 在 Honcho 退出后才停
7. 崩溃后恢复：再次 uv run dbx-graphiti start 时，journal 自动按序重放所有未完成 mutation 重建图
8. 跨环境复用：所有可执行与数据都缓存到本地目录，新机器 clone 后只需 uv run dbx-graphiti start 一次即可恢复运行

适用场景

• Databricks 用户做 Agent 记忆层：在 Databricks Model Serving 环境下构建有状态的 AI Agent，知识图谱由 Databricks 模型驱动
• 本地优先的 Graphiti 体验：想用 Graphiti 但不想装 Docker / Podman 的开发者
• 多租户 Graphiti 服务：用 JOURNAL_NAMESPACE 隔离不同业务线的图谱数据
• 生产级 Agent 持久化：写前日志 + 启动回放保证 at-least-once 语义，可用于跨实例重建
• MCP 兼容 Agent 的"图谱后端即服务"：Claude Code / Cursor / Continue / 自研 Agent 都可以通过标准 HTTP MCP 接入
• CI / 集成测试：快速拉起 / 停服 Graphiti 跑端到端测试，避免 docker-compose 依赖

适用人群

• Databricks Model Serving 重度用户，希望把 Graphiti 知识图谱与 Databricks 模型栈原生集成
• 偏好本地进程部署（无 Docker）的工程师 / DevOps
• 构建有状态 AI Agent、需要持久化知识图谱的 Agent 开发者
• 评估 Graphiti 31k Stars 项目但被容器依赖劝退的早期采用者

工作原理

dbx-tools-graphiti 启动时按依赖顺序拉起三个本地进程：dbx-model-proxy（桥接 Databricks Model Serving 鉴权）、Neo4j Community 5.26（图存储）、Graphiti HTTP MCP（暴露标准 MCP 协议）。所有缺失依赖（Java 21 / uv / Neo4j / Graphiti 源码）通过 mise 按需安装；下载 / 凭据 / 日志 / 数据全部缓存到 ~/.cache/dbx-tools/graphiti/ 等本地目录，第二次启动秒级就绪。Honcho 作为 supervisor 把 Graphiti 与 model proxy 编入同一进程组，SIGTERM 广播、5 秒宽限后 SIGKILL 兜底，保证停服时不留僵尸进程。写操作经过 DelegatingGraphDriver：所有 Cypher mutation 先 append 到 Postgres JSONB journal（PostgresWriteStorage 提供持久化实现），再提交图操作；启动首次索引设置时清空图并按序回放 journal（不重复 journaling），实现 write-ahead attempt recovery + at-least-once replay 语义。Databricks 鉴权通过 dbx-model-proxy 透明转发：本地用 profile，Databricks App 用 ambient service-principal，CI 用 DATABRICKS_CONFIG_PROFILE 环境变量。所有版本（Graphiti、Neo4j）pin 死，确保环境可重复。

官方链接

• PyPI：https://pypi.org/project/dbx-tools-graphiti/
• GitHub：https://github.com/reggie-db/dbx-tools
• 上游 Graphiti：https://github.com/getzep/graphiti
• MCP 端点（启动后）：http://127.0.0.1:8000/mcp/