AI Agent 图记忆脚手架 create-context-graph 完全指南:5 分钟生成你的领域专属智能体应用

原创2026-10-30 12:13:311,386 阅读

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 图记忆脚手架 create-context-graph 用图谱替代扁平存储

能力 向量库 知识图谱(上下文图)
语义相似度检索 优秀 良好(配合嵌入)
精确关系查询 差 优秀
多跳推理 不支持 原生支持
可解释的连接关系 无 有

核心洞察一句话:向量能找"相似"的东西,图谱能找"相关"的东西——AI Agent 两者都需要,而图记忆脚手架让后者开箱即用。

二、一条命令生成什么?

运行后你得到的是一个可直接运行的完整项目:

# 自托管 Neo4j + 完整演示数据
uvx create-context-graph my-app --domain healthcare --framework pydanticai --self-hosted --demo

# 交互式向导模式
npx create-context-graph

生成的应用采用经典的三栏布局:左侧与智能体流式对话(工具调用实时可视化)、中间是可拖拽缩放的交互图谱、右侧是决策追踪与文档浏览器。

生成的应用三栏界面:AI Agent 图记忆应用包含聊天、图谱可视化和文档浏览器

项目结构(节选)如下,一份领域本体 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,就能定制整个应用。

从本体 YAML 到生成代码的流水线:create-context-graph 图记忆脚手架核心机制

三、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 链,每步记录思考、动作、观察),这正是医疗、金融等高合规场景需要的可审计能力。

决策追踪图谱结构:AI Agent 图记忆中的可审计推理链路

四、三大记忆类型如何协同?

每个生成的应用都内置三种记忆的完整实现:

记忆类型 作用 存储形式
短期记忆 当前会话上下文 按会话存储的消息节点
长期记忆 持久化领域知识 POLE+O 实体知识图谱
推理记忆 决策审计轨迹 DecisionTrace → TraceStep 链

三类记忆协同工作:AI Agent 图记忆架构在单次聊天请求中的流转

这意味着 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

SaaS 连接器数据流:真实业务数据汇入 Neo4j 知识图谱

亮点包括:

  • 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 → 图谱增量更新):

create-context-graph 整体架构:AI Agent 图记忆应用的生成管线与运行时组件

八、常见问题排查

问题 解决方法
聊天时报 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

九、延伸阅读

小结:create-context-graph 把"AI Agent + 图记忆"这件复杂的事压缩成一条命令。选一个领域、挑一个框架,5 分钟后你就拥有一个会推理、能追溯、可对话的领域专属智能体应用——上手成本极低,想象空间很大。🚀

登录后查看全文
create-context-graph