AI Agent 图记忆脚手架 create-context-graph 完全指南:5 分钟生成你的领域专属智能体应用
AI Agent 图记忆脚手架 create-context-graph 完全指南:5 分钟生成你的领域专属智能体应用
create-context-graph 是一款来自 Neo4j Labs 的命令行脚手架工具,专为构建 AI Agent 图记忆应用而设计:你只需指定一个业务领域和智能体框架,它就能在 5 分钟内生成一个完整的全栈应用——包括带图记忆推理能力的 AI 智能体后端、可交互的知识图谱可视化前端,以及预置的演示数据。本文带你从零理解它的核心概念,并手把手跑通第一个领域专属智能体应用。
一、为什么 AI Agent 需要"上下文图"记忆?
🤔 传统 AI Agent 的记忆通常是"扁平"的:聊天日志是线性消息,向量库是一堆文本片段,彼此之间没有关系。这导致 Agent 无法回答"昨天讨论的患者有新诊断了"这类需要跨会话、跨实体关联的问题。
create-context-graph 的答案是 上下文图(Context Graph):把记忆组织成一张 Neo4j 知识图谱,实体(人、组织、地点、事件、对象,即 POLE+O 模型)之间用带类型的关系连接,并完整记录决策推理链路。
| 能力 | 向量库 | 知识图谱(上下文图) |
|---|---|---|
| 语义相似度检索 | 优秀 | 良好(配合嵌入) |
| 精确关系查询 | 差 | 优秀 |
| 多跳推理 | 不支持 | 原生支持 |
| 可解释的连接关系 | 无 | 有 |
核心洞察一句话:向量能找"相似"的东西,图谱能找"相关"的东西——AI Agent 两者都需要,而图记忆脚手架让后者开箱即用。
二、一条命令生成什么?
运行后你得到的是一个可直接运行的完整项目:
# 自托管 Neo4j + 完整演示数据
uvx create-context-graph my-app --domain healthcare --framework pydanticai --self-hosted --demo
# 交互式向导模式
npx create-context-graph
生成的应用采用经典的三栏布局:左侧与智能体流式对话(工具调用实时可视化)、中间是可拖拽缩放的交互图谱、右侧是决策追踪与文档浏览器。
项目结构(节选)如下,一份领域本体 YAML 驱动全部代码生成:
my-app/
├── backend/ # FastAPI + AI Agent(框架可选)
├── frontend/ # Next.js + Chakra UI 前端
├── cypher/ # Neo4j 约束、索引与 GDS 投影
├── data/
│ ├── ontology.yaml # 领域本体定义
│ └── fixtures.json # 预生成示例数据
└── Makefile # start / seed / reset / install
从领域 YAML 到可运行代码
整个生成过程由领域本体文件(位于 src/create_context_graph/domains/,如 healthcare.yaml)驱动,经 ontology.py 校验合并后,通过 Jinja2 模板(renderer.py)渲染出后端、前端、Cypher 模式和演示数据——改一份 YAML,就能定制整个应用。
三、5 分钟快速上手
1. 环境准备(1 分钟)
- Python 3.11+(推荐搭配
uv) - Node.js 18+(前端需要)
- 二选一的记忆后端:
- NAMS(默认):托管记忆服务,无需安装 Neo4j,图谱从空白开始、随聊随建
- 自托管(
--self-hosted):Docker / Aura / neo4j-local 任一方式运行 Neo4j 5+,可加载完整演示数据
- 一个 LLM API Key(如
ANTHROPIC_API_KEY)
2. 生成项目(约 30 秒)
# 方式 A:NAMS 托管记忆(无需 Neo4j)
uvx create-context-graph my-app \
--domain healthcare \
--framework strands \
--nams-api-key sk-nams-...
# 方式 B:自托管 Neo4j + 完整演示数据(推荐新手体验)
uvx create-context-graph my-app \
--domain healthcare \
--framework pydanticai \
--self-hosted \
--demo
3. 启动应用(约 2 分钟)
cd my-app
echo 'ANTHROPIC_API_KEY=sk-ant-...' >> .env
make install
make start # 自托管模式先执行 make docker-up && make seed
打开 http://localhost:3000 即可对话。--demo 模式会预置约 85 个实体、180 条关系、25 份专业文档和 4 条决策追踪,第一屏就能看到完整图谱。
4. 上手试几个问题
- "列出所有确诊 2 型糖尿病的患者"
- "Chen 患者当前处方中有无禁忌药物?"
- "Memorial 医院有哪些关联的心血管科医生?"
对话时注意右侧面板:Agent 会依次调用 Cypher 工具、流式返回结果,推理步骤完整保留为决策追踪(DecisionTrace → TraceStep 链,每步记录思考、动作、观察),这正是医疗、金融等高合规场景需要的可审计能力。
四、三大记忆类型如何协同?
每个生成的应用都内置三种记忆的完整实现:
| 记忆类型 | 作用 | 存储形式 |
|---|---|---|
| 短期记忆 | 当前会话上下文 | 按会话存储的消息节点 |
| 长期记忆 | 持久化领域知识 | POLE+O 实体知识图谱 |
| 推理记忆 | 决策审计轨迹 | DecisionTrace → TraceStep 链 |
这意味着 Agent 不只是"检索文本",而是在结构化知识图上推理:既能多跳遍历("找出曾在 X 医院受训的医生治疗过的所有患者"),又能回溯每个结论的证据来源。
五、27 个内置领域 + 8 种智能体框架
🎯 内置领域覆盖从医疗、金融、法律到游戏、野生动物管理的 27 个行业,每个领域都自带本体、Agent 工具、演示场景和夹具数据,目录见 docs/docs/reference/domain-catalog.md:
healthcare:患者、医生、诊断、治疗方案financial-services:账户、交易、决策、合规software-engineering:仓库、Issue、PR、部署cybersecurity:资产、漏洞、告警、事件product-management、legal、education、gaming…… 等 27 个
查看完整列表:uvx create-context-graph --list-domains。如果列表里没有你的行业,用自然语言描述即可——LLM 会自动生成一份完整本体:
uvx create-context-graph my-app \
--custom-domain "veterinary clinic management" \
--framework pydanticai --self-hosted --demo
框架方面支持 8 种主流 AI Agent 框架,同一套后端 API、前端和图谱,只切换 Agent 实现:
| 框架 | 说明 | 所需 Key |
|---|---|---|
| Strands(默认) | AWS 工具调用 Agent | ANTHROPIC_API_KEY |
| PydanticAI | Pydantic 结构化工具定义 | ANTHROPIC_API_KEY |
| Claude Agent SDK | Anthropic 原生 agentic 循环 | ANTHROPIC_API_KEY |
| OpenAI Agents SDK | @function_tool 装饰器 | OPENAI_API_KEY |
| LangGraph | 有状态图工作流 | ANTHROPIC_API_KEY |
| CrewAI | 多智能体协作 | ANTHROPIC_API_KEY |
| Google ADK | Gemini FunctionTool | GOOGLE_API_KEY |
| Anthropic Tools | 模块化工具注册表 | ANTHROPIC_API_KEY |
六、导入真实业务数据:13 个 SaaS 连接器
不想只用演示数据?脚手架支持在生成时一键接入你现有工具的数据(GitHub、Slack、Jira、Notion、Gmail、Google Calendar、Salesforce、Linear、Google Workspace、Claude Code、Claude AI、ChatGPT 和本地文件):
uvx create-context-graph my-app \
--domain personal-knowledge --framework pydanticai --self-hosted \
--connector github --connector slack
亮点包括:
- Claude Code / Claude AI / ChatGPT 连接器直接读取本地导出文件,无需任何 API Key,自动脱敏密钥
- Google Workspace 把文档中的已解决评论线程提取为一等公民决策追踪
- 连接器会一并生成到项目中,之后
make import随时重新导入
连接器源码位于 src/create_context_graph/connectors/,每种服务一个独立模块。
七、进阶玩法速览
- MCP 服务:加
--with-mcp生成 MCP 配置,让 Claude Desktop 与 Web 应用共享同一张知识图谱 - 自定义记忆 Provider:通过
MEMORY_LLM/MEMORY_EMBEDDING环境变量用 LiteLLM 字符串指定实体抽取 LLM 与嵌入模型(Anthropic、OpenAI、Bedrock、Ollama 等) - 架构全貌:下图上半部分是生成管线(CLI → Jinja2 → 后端 + 前端 + 数据),下半部分是运行时(前端 SSE 流式对话 → Agent 执行 Cypher → 图谱增量更新):
八、常见问题排查
| 问题 | 解决方法 |
|---|---|
聊天时报 ANTHROPIC_API_KEY not set |
将 Key 追加到 .env |
| NAMS 认证失败 | 到 NAMS 控制台重新生成 API Key |
| 图谱视图没有边(NAMS 模式) | 预期行为,NAMS REST 暂不支持关系写入;换 --self-hosted 获得完整图谱 |
make seed 连接失败 |
确认 Neo4j 已启动、凭据正确,可用 make test-connection 检查 |
| 端口 3000/8000 被占用 | 停止占用进程,或修改 .env 中的 BACKEND_PORT / FRONTEND_PORT |
九、延伸阅读
- 快速上手:docs/docs/quick-start.md
- 第一个完整教程:docs/docs/tutorials/first-context-graph-app.md
- 为什么需要上下文图:docs/docs/explanation/why-context-graphs.md
- 三种记忆类型详解:docs/docs/explanation/three-memory-types.md
- 领域本体如何工作:docs/docs/explanation/how-domain-ontologies-work.md
- 完整 CLI 参数:docs/docs/reference/cli-options.md
小结:create-context-graph 把"AI Agent + 图记忆"这件复杂的事压缩成一条命令。选一个领域、挑一个框架,5 分钟后你就拥有一个会推理、能追溯、可对话的领域专属智能体应用——上手成本极低,想象空间很大。🚀






