mcpField
N
neo4j-agent-memory-skill

neo4j-agent-memory-skill

github.com/neo4j-contribAgent 工作流118893 次安装1 周前更新
代码仓库

关于 neo4j-agent-memory-skill

neo4j-agent-memory-skill 是介绍 neo4j-agent-memory 的参考技能，面向需要为 AI Agent 构建持久图记忆的开发者。该项目以单一 Neo4j 图存储短期、长期和推理记忆，并提供库、MCP 服务及托管服务等使用方式。

主要功能

  1. 01短期、长期与推理记忆
  2. 02基于 POLE+O 构建实体图
  3. 03对话与推理轨迹存储
  4. 04提供本地及托管使用方式
  5. 05支持多种 Agent 框架集成
  6. 06多阶段实体抽取与去重

适用场景

  1. 01为 Agent 保存跨会话对话记忆
  2. 02从对话构建实体和关系图
  3. 03记录工具调用与决策过程
  4. 04为不同 Agent 框架接入图记忆

MCP 相关

该项目提供本地 MCP 服务，将记忆操作作为工具暴露给兼容客户端；另有托管 MCP 端点，使用 Streamable HTTP 和 bearer token。

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/neo4j-contrib/neo4j-skills --skill neo4j-agent-memory-skill

安装后在 Claude Code 中输入/neo4j-agent-memory-skill确认已加载。

附带文件README.md

详细介绍

neo4j-agent-memory

neo4j-agent-memory Python 包的权威参考——这是 Neo4j Labs 项目，可在单个知识图谱中为 AI Agent 提供三个不同的记忆层（短期、长期和推理）。

⚠️ 撰写前请核实权威信息。 版本号、额外依赖项、工具数量和 API 范围会随版本变化。本技能中的数值反映的是特定时间点的信息。发布任何与版本有关的内容前，请对照 PyPI（https://pypi.org/project/neo4j-agent-memory/）和 GitHub README（https://github.com/neo4j-labs/agent-memory）进行确认。PyPI 是版本号的权威来源，切勿自行推断。

适用场景

  • 构建需要由 Neo4j 支持持久化记忆（短期记忆、长期记忆、推理轨迹）的 AI Agent
  • 使用 neo4j-agent-memory Python 包或托管的 NAMS 服务 memory.neo4jlabs.com
  • 将 Agent 记忆集成到 LangChain、PydanticAI、CrewAI、AWS Strands、Google ADK、OpenAI Agents、LlamaIndex 或 Microsoft Agent Framework
  • 编写有关图原生 Agent 记忆的文档、教程或定位内容
  • 比较图原生记忆与纯向量方案

不适用场景

  • 普通 Neo4j 驱动连接（不需要记忆层）→ 使用 neo4j-driver-python-skill
  • 编写或优化 Cypher 查询 → 使用 neo4j-cypher-skill
  • GraphRAG 检索流水线 → 使用 neo4j-graphrag-skill

项目概览

字段值
包neo4j-agent-memory
PyPIhttps://pypi.org/project/neo4j-agent-memory/
GitHubhttps://github.com/neo4j-labs/agent-memory
官方文档https://neo4j.com/labs/agent-memory/
托管服务https://memory.neo4jlabs.com（NAMS——早期访问，尚未在官方项目页面中记录）
托管 MCP 端点https://memory.neo4jlabs.com/mcp（Streamable HTTP，Bearer 身份验证）
许可证Apache-2.0
Python3.10+
Neo4j5.20+（向量索引所需）
状态实验性（Neo4j Labs，社区支持）
当前版本（撰写时）0.7.0（2026-10-07）——引用前务必核实 PyPI 信息

一句话介绍

面向 AI Agent 的图原生记忆系统，可存储对话、构建知识图谱并记录 Agent 推理——所有内容都以互相关联的节点形式存储在单个 Neo4j 数据库中。

使用方式

neo4j-agent-memory 提供两种使用方式。它们属于同一个底层项目，区别在于运行方式、身份验证方式以及由谁负责管理。

选项说明适用情况
自托管库pip install neo4j-agent-memory + 自有 Neo4j（本地 / Docker / Aura）。完整的 Python API、本地 MCP 服务和框架集成都在你的进程中运行。开发、本地部署的数据、自定义提取流水线、需要完全控制，或自行提供嵌入模型 / 大模型。
托管服务（NAMS）位于 https://memory.neo4jlabs.com 的托管服务。每个工作区使用隔离的 Neo4j Aura 数据库，并提供 REST API、远程 MCP 端点和 Web 控制台。零基础设施试用、在多个 Agent / 机器间共享记忆、演示，或不想运行 Neo4j 的团队。

⚠️ NAMS 可以访问，但尚未在 GitHub README 或 neo4j.com/labs/agent-memory/ 中提及。 请将其视为早期访问 / 软启动服务。在已发布的内容中，不要声称其提供 SLA、定价或已正式发布。详情请参阅下文的**托管服务（NAMS）**章节。

三种记忆类型

这是该架构的标志性特征。描述项目的每一处内容都应首先介绍这三种类型。

记忆类型存储内容颜色约定
短期对话消息、会话历史、顺序消息链、按元数据筛选的搜索、大模型驱动的摘要绿色（#B2F2BB / #2F9E44）
长期实体（人物、地点、组织）、偏好、事实及其相互关系——通过 POLE+O 模型从对话中自动构建橙色/黄色（#FFEC99 / #F08C00）
推理决策轨迹、工具调用来源、思考-行动-结果链——让 Agent 能够从自身过去的推理模式中学习紫色（#D0BFFF / #9C36B5）

推理记忆是主要的竞争差异化优势。 大多数竞品系统都涵盖短期记忆和长期记忆，却将推理记忆视为次要功能，甚至完全省略。进行产品定位时，应重点突出这一点。

POLE+O 模型

长期记忆使用 POLE+O 实体框架——这是本项目的标准实体分类：

  • Person（人物）
  • Organization（组织）
  • Location（地点）
  • Event（事件）
  • +O Object（对象，任何不属于前四类的事物——产品、概念、项目等）

绘制数据模型图时，实体节点使用椭圆，关系使用带标签的箭头（UPPER_SNAKE_CASE），并遵循 Neo4j Browser 的惯例。

安装

安装核心包并添加扩展。扩展安装方式为 pip install neo4j-agent-memory[<extra>]。

pip install neo4j-agent-memory                  # Core
pip install neo4j-agent-memory[openai]          # + OpenAI embeddings
pip install neo4j-agent-memory[mcp]             # + MCP server
pip install neo4j-agent-memory[langchain]       # + LangChain
pip install neo4j-agent-memory[all]             # Everything

完整扩展列表（可能变更——请在 PyPI 上核实）：all、anthropic、aws、bedrock、cli、crewai、extraction、full、fuzzy、gliner、google、google-adk、instructor、langchain、langchain-agents、litellm、llamaindex、mcp、microsoft-agent、nams、observability、openai、openai-agents、opentelemetry、opik、pydantic-ai、sentence-transformers、spacy、strands、vertex-ai。

Python API（快速入门）

标准导入模式和基本用法。教程和示例应采用这种形式。

import asyncio
from neo4j_agent_memory import MemoryClient, MemorySettings

async def main():
    settings = MemorySettings(
        neo4j={"uri": "bolt://localhost:7687", "password": "your-password"}
    )

    async with MemoryClient(settings) as memory:
        # Short-term: store a conversation message
        await memory.short_term.add_message(
            session_id="user-123",
            role="user",
            content="Hi, I'm John and I love Italian food!"
        )

        # Long-term: build the knowledge graph
        await memory.long_term.add_entity("John", "PERSON")
        await memory.long_term.add_preference(
            category="food",
            preference="Loves Italian cuisine"
        )

        # Get combined context for an LLM prompt
        context = await memory.get_context(
            "What restaurant should I recommend?",
            session_id="user-123"
        )
        print(context)

asyncio.run(main())

请注意异步上下文管理器模式（async with MemoryClient(settings) as memory:）——这是标准形式。

MCP 服务

将记忆作为工具提供给兼容 MCP 的 AI 助手（Claude Desktop、Claude Code、Cursor、VS Code Copilot）。

调用方式

权威的一行命令（无需安装）：

uvx "neo4j-agent-memory[mcp]" mcp serve --password <neo4j-password>

本地安装方式：

neo4j-agent-memory mcp serve --password <pw>
传输方式和配置
# stdio (default — Claude Desktop, Claude Code)
neo4j-agent-memory mcp serve --password <pw>

# Streamable HTTP (network; endpoint /mcp/). `--transport sse` deprecated — serves Streamable HTTP with warning
neo4j-agent-memory mcp serve --transport http --port 8080 --password <pw>

# Core profile — fewer tools, less context overhead
neo4j-agent-memory mcp serve --profile core --password <pw>

# Session continuity across conversations
neo4j-agent-memory mcp serve \
  --session-strategy per_day \
  --user-id alice \
  --password <pw>
工具配置
配置工具内容
core6memory_search、memory_get_context、memory_store_message、memory_add_entity、memory_add_preference、memory_add_fact
extended（默认）16Core + 对话历史、实体详情、图谱导出、关系创建、推理轨迹、观察记录、只读 Cypher

从 v0.1.1 起，memory_add_fact 支持 metadata 参数，其功能与 memory_add_entity 相当。

Claude Code 注册
claude mcp add neo4j-agent-memory -- \
  uvx "neo4j-agent-memory[mcp]" mcp serve --password <neo4j-password>
Claude Desktop 配置
{
  "mcpServers": {
    "neo4j-agent-memory": {
      "command": "uvx",
      "args": ["neo4j-agent-memory[mcp]", "mcp", "serve", "--password", "your-password"],
      "env": {
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

关于 memory.neo4jlabs.com/mcp 上的托管 MCP 端点，请参阅下方的 **托管服务（NAMS）**部分——它使用 Streamable HTTP 传输和 bearer-token 身份验证，而非本地 uvx 调用。

托管服务（NAMS）

NAMS——Neo4j Agent Memory Service——是 neo4j-agent-memory 的托管部署，网址为 https://memory.neo4jlabs.com。它集成了 REST API、MCP 服务、Web 控制台和每个工作区各自的 Neo4j Aura 数据库。

⚠️ 引用前请对照在线服务核实。 NAMS 未在 GitHub README 或 neo4j.com/labs/agent-memory/ 上记录。端点形式、工具数量、身份验证流程和限制可能在没有发布说明的情况下发生变化。发布任何与 NAMS 相关的内容前，请重新检查在线网站和 /openapi.json 中的 OpenAPI 规范。

服务接口
  • 基础 URL： https://memory.neo4jlabs.com
  • Web 控制台： 根 URL — 工作区管理、记忆浏览、实体可视化
  • REST API： https://memory.neo4jlabs.com/v1/ — OpenAPI 规范位于 /openapi.json；涵盖对话、实体、观察结果、推理轨迹和只读 Cypher
  • MCP 端点： https://memory.neo4jlabs.com/mcp — Streamable HTTP 传输，提供托管工具集，使用 bearer token 进行身份验证
身份验证
  • API 密钥，前缀为 nams_，可在 Web 控制台中创建和轮换 — 用作 REST 和 MCP 的 bearer token
  • Auth0 OAuth2 (PKCE) + 用于交互式用户流程的作用域 JWT

请勿将这些凭据与可自托管库的 --password Neo4j 凭据混淆——它们用于技术栈的不同部分。

存储模型

每个工作区都由一个隔离的 Neo4j Aura 数据库提供支持，按需配置。也支持自带 Neo4j，并可针对每个工作区单独配置。

速率限制

使用量计数器按 API 密钥／工作区进行跟踪。具体限制尚未公开说明——在向客户承诺具体数字前，请查看控制台或再次向服务核实。

Claude Code 注册（托管 MCP）
claude mcp add --transport http neo4j-agent-memory-hosted \
  https://memory.neo4jlabs.com/mcp \
  --header "Authorization: Bearer <nams_api_key>"
Claude Desktop 配置（托管 MCP）
{
  "mcpServers": {
    "neo4j-agent-memory-hosted": {
      "url": "https://memory.neo4jlabs.com/mcp",
      "type": "http",
      "headers": {
        "Authorization": "Bearer nams_..."
      }
    }
  }
}

框架集成

所有集成都位于 neo4j_agent_memory.integrations.<framework> 下。请安装对应的额外依赖。

框架安装额外依赖导入
LangChain[langchain]from neo4j_agent_memory.integrations.langchain import Neo4jAgentMemory
Pydantic AI[pydantic-ai]from neo4j_agent_memory.integrations.pydantic_ai import MemoryDependency
Google ADK[google-adk]from neo4j_agent_memory.integrations.google_adk import Neo4jMemoryService
AWS Strands[strands]from neo4j_agent_memory.integrations.strands import context_graph_tools
CrewAI[crewai]from neo4j_agent_memory.integrations.crewai import Neo4jCrewMemory
LlamaIndex[llamaindex]from neo4j_agent_memory.integrations.llamaindex import Neo4jLlamaIndexMemory
OpenAI Agents[openai-agents]from neo4j_agent_memory.integrations.openai_agents import ...
Microsoft Agent Framework[microsoft-agent]from neo4j_agent_memory.integrations.microsoft_agent import Neo4jMicrosoftMemory

实体抽取流程

多阶段抽取（按成本／质量权衡，从最快到最准确）：

  1. spaCy — 快速的统计式 NER，成本最低，覆盖面广但不够精准
  2. GLiNER — 使用类型化模式进行零样本实体抽取；使用 GLiREL 抽取关系
  3. LLM 回退 — 最准确、成本最高；在结构丰富或含糊不清时使用

丰富化是独立的后台阶段：Wikipedia 和 Diffbot 可以为抽取出的实体补充上下文信息。

去重（v0.1.1+）通过匹配主体／谓词并结合嵌入相似度（阈值约为 0.95），自动合并重复事实和偏好，并更新置信度，而不是创建新节点。可通过 DeduplicationConfig 进行调优。

需要了解的配置对象：ExtractionConfig、DeduplicationConfig、MemoryIntegration、SessionStrategy。

定位用语

以下表述至关重要。尽可能原样使用。

核心标语
  • “图负责理解；向量负责相似度。”
  • “向量存储带来回忆。图带来理解。”
  • “三种记忆类型，一个知识图谱。”
类别定位
  • 在适合的场合，引用 Foundation Capital 的 “AI's Trillion-Dollar Opportunity: Context Graphs” 理念。
  • neo4j-agent-memory 被定位为上下文图谱类别的完整实现——它涵盖全部三个记忆层，而不仅仅是两个。
  • 上下文图谱与领域数据共存于同一个 Neo4j 实例中（而非外挂的外部系统）。这是架构图中的一个关键概念／视觉要点。
建议表述
  • “图原生记忆”
  • “上下文图”
  • “三个独立的记忆层”
  • “将推理轨迹作为一等图节点”
  • “从过往推理中学习”
  • “根据对话自动构建知识图谱”
  • “Neo4j Labs 项目” / “实验性” / “社区支持”
避免表述
  • 不要在已发布的内容中点名具体竞品（Mem0、Zep、Letta、Cognee、Supermemory）。请围绕功能而非产品名称进行比较。
  • 不要称其为“已可用于生产环境”（这是一个 Labs 项目——完整的语气指南请参阅 neo4j-labs-brand 技能）。
  • 不要说“官方支持”，也不要暗示提供 SLA。

需要留意的常见修正

编辑或审核有关此项目的内容时，请检查以下事项：

  1. 版本号过时——如今仍写“v0.1.0”的人可能参考了过时的笔记；请核实 PyPI。
  2. 规范文档 URL 错误——正确地址是 neo4j.com/labs/agent-memory，而不是 Vercel 预览 URL。
  3. 臆测 API 接口——如果代码示例未经运行验证，请标出；优先采用 GitHub README 或官方示例中的模式。
  4. 缺少 “Labs” 定位——应明确说明它具有实验性并由社区支持。
  5. 与其他 Neo4j MCP 服务混淆——这类服务有多个（mcp-neo4j-cypher、mcp-neo4j-memory——旧版知识图谱记忆服务等）。neo4j-agent-memory 的 MCP 服务有所不同，并作为软件包的一部分随 [mcp] extra 一同发布。
  6. 将 NAMS 与可自托管库混淆——两者基于同一项目，但使用方式不同。连接字符串、身份验证和工具集均不相同：可自托管版本使用本地 uvx 调用和 Neo4j --password；NAMS 使用 Streamable HTTP MCP URL 和以 nams_ 为前缀的 bearer token。请勿混用。
  7. 过度承诺 NAMS 的可用性——GitHub README 或 neo4j.com/labs/agent-memory/ 尚未提及托管服务。避免使用“官方支持”、SLA、定价声明或“已可用于生产环境”等表述。应将其视为早期体验服务。

生态系统中的相关项目

经常会提及以下项目；请识别并使用正确名称。

项目说明
create-context-graphCLI 脚手架（uvx create-context-graph），可生成预先接入 neo4j-agent-memory 的全栈上下文图应用。规范文档：create-context-graph.dev。
Lenny's Podcast Memory Explorer标志性演示——包含 299 期播客、知识图谱、地理空间地图和 Wikipedia 内容增强。基于 PydanticAI。源代码：https://github.com/neo4j-labs/agent-memory/tree/main/examples/lennys-memory
neo4j-agent-integrations更广泛的框架集成项目集合，其中许多集成会通过 [<framework>] extras 打包到 neo4j-agent-memory 中。
agent-memory-tck技术合规套件——用于多语言、多框架互操作性（多语言生态）的行为规范。
Microsoft Learn integrationMicrosoft Agent Framework 官方文档将 neo4j-agent-memory 列为 Neo4j Memory Provider。

规范示例（来自 neo4j-labs/agent-memory 仓库）

请引导用户查看上游示例，而不是自行编写示例。以下所有项目都位于 https://github.com/neo4j-labs/agent-memory/tree/main/examples 的 examples/ 目录下：

图示规范（交叉引用）

为本项目构建图示时，请结合以下技能：

  • excalidraw 技能 — JSON 格式和项目的图示管理脚本
  • neo4j-styleguide 技能 — Cypher 代码风格和 Neo4j 品牌颜色
  • neo4j-labs-brand 技能 — Labs 紫色（#6366F1）、状态徽章、免责声明措辞

记忆类型颜色（在所有图示中保持一致）：

Short-Term:  #B2F2BB fill / #2F9E44 stroke  (green)
Long-Term:   #FFEC99 fill / #F08C00 stroke  (orange/yellow)
Reasoning:   #D0BFFF fill / #9C36B5 stroke  (purple)
Neo4j/Store: #A5D8FF fill / #1971C2 stroke  (blue)
Labs accent: #6366F1 (purple, for Labs branding elements)

文档结构（交叉引用）

neo4j.com/labs/agent-memory 上的规范文档遵循 Diataxis 框架（详情请参阅本项目中的 diataxis 技能）：

  • 教程 — 构建你的第一个启用记忆的 Agent
  • 操作指南 — 实体提取、去重、丰富、集成
  • 参考 — 配置、CLI、MCP 工具、API
  • 说明 — POLE+O 模型、记忆类型、提取管道

添加新内容时，请将其放在正确的类别中。

快速权威事实检查清单

发布有关本项目的任何内容之前，请确认：

  • 版本号与 PyPI 当前版本一致（不要根据说明推断）
  • 规范文档链接指向 neo4j.com/labs/agent-memory
  • 三种记忆类型名称正确（短期、长期、推理）
  • POLE+O 模型名称保持一致（不是 POLEO，也不是 POLE-O）
  • 相关时注明 Python ≥ 3.10 和 Neo4j ≥ 5.20 的要求
  • README/落地页内容中包含 Labs 免责声明
  • 发布内容中不出现竞争对手名称
  • 明确指出推理记忆是差异化优势
  • 导入路径使用 neo4j_agent_memory.integrations.<framework>（下划线、snake_case）
  • 如果提及 NAMS，请明确区分它与可自托管库，并根据在线服务重新核实端点（尚未同步到 README）

资源

检查清单

  • 版本：引用前检查 PyPI
  • 使用模式：可自托管还是使用 NAMS
  • 已安装正确的额外依赖（neo4j-agent-memory[<extra>]）
  • MemoryClient 用作异步上下文管理器
  • 明确写出三种类型：短期／长期／推理
  • POLE+O 始终一致（不要写成 POLEO 或 POLE-O）
  • NAMS：强调早期访问；不提 SLA 或定价
  • 不要将凭据硬编码；NAMS bearer token 与 Neo4j --password 分开

评论

支持 Markdown