使用 neo4j-agent-memory 为 AI…

当需要编写、审阅或发布关于 neo4j-agent-memory 包、NAMS 托管服务、POLE+O 模型、MCP 服务器或各框架集成的文档、教程、博客与代码示例时，用这套做法确保内容准确、版本正确、定位一致。

适用场景

解决思路

1. 发布任何版本敏感内容前，先到 PyPI（https://pypi.org/project/neo4j-agent-memory/）和 GitHub README（https://github.com/neo4j-labs/agent-memory）核对权威状态；版本号以 PyPI 为准，绝不凭笔记推断。
2. 明确区分两种消费模式：自托管库（pip install neo4j-agent-memory + 自备 Neo4j，本地 MCP、进程内集成）与托管服务 NAMS（https://memory.neo4jlabs.com，按工作区隔离的 Neo4j Aura、REST API、远程 MCP、Web 控制台），不要混用连接串、认证方式和工具集。
3. 内容开头始终先讲三种记忆类型：短期（对话消息、会话历史、顺序消息链、元数据过滤搜索、LLM 摘要）、长期（实体、偏好、事实及其关系，经 POLE+O 自动构建）、推理（决策轨迹、工具调用溯源、thought-action-outcome 链）；并把推理记忆作为核心差异化点重点突出。
4. 长期记忆统一使用 POLE+O 实体分类：Person、Organization、Location、Event、+Object（产品、概念、项目等），写作时保持拼写一致（不要写成 POLEO 或 POLE-O）。
5. 画数据模型图时，实体节点用椭圆，关系用 UPPER_SNAKE_CASE 标签箭头，遵循 Neo4j Browser 约定；记忆类型配色保持一致：短期 #B2F2BB/#2F9E44、长期 #FFEC99/#F08C00、推理 #D0BFFF/#9C36B5、Neo4j/存储 #A5D8FF/#1971C2、Labs 强调色 #6366F1。
6. 安装示例使用 extras 模式 pip install neo4j-agent-memory[<extra>]，按需列出：核心、[openai]、[mcp]、[langchain]、[all]；完整 extras 列表（all、anthropic、aws、bedrock、cli、crewai、extraction、full、fuzzy、gliner、google、google-adk、langchain、llamaindex、mcp、microsoft-agent、observability、openai、openai-agents、opentelemetry、opik、pydantic-ai、sentence-transformers、spacy、strands、vertex-ai）以 PyPI 为准。
7. Python 示例采用规范形式：from neo4j_agent_memory import MemoryClient, MemorySettings，并用 async with MemoryClient(settings) as memory: 异步上下文管理器；演示 short_term.add_message、long_term.add_entity、long_term.add_preference 和 get_context。
8. MCP 服务器调用优先给出免安装一行命令：uvx "neo4j-agent-memory[mcp]" mcp serve --password <neo4j-password>；本地安装替代为 neo4j-agent-memory mcp serve --password <pw>。
9. 按场景选择 MCP 传输与配置：stdio（默认，Claude Desktop/Claude Code）、SSE（--transport sse --port 8080）、core 精简配置（--profile core）、会话连续性（--session-strategy per_day --user-id alice）。
10. 介绍工具配置档：core 含 6 个工具（memory_search、memory_get_context、memory_store_message、memory_add_entity、memory_add_preference、memory_add_fact）；extended（默认）含 16 个工具，额外覆盖对话历史、实体详情、图导出、关系创建、推理轨迹、观察、只读 Cypher；v0.1.1 起 memory_add_fact 支持 metadata 参数。
11. 给出 Claude Code 注册命令：claude mcp add neo4j-agent-memory -- uvx "neo4j-agent-memory[mcp]" mcp serve --password <neo4j-password>；以及 Claude Desktop 的 JSON 配置（command 为 uvx，args 含 neo4j-agent-memory[mcp]、mcp、serve、--password，env 中放 OPENAI_API_KEY）。
12. 引用 NAMS 前先核对线上服务与 /openapi.json：基础 URL https://memory.neo4jlabs.com，REST API 在 /v1/，MCP 端点在 /mcp（SSE，bearer 认证）；认证用 nams_ 前缀 API key（bearer token）或 Auth0 OAuth2 (PKCE) + 作用域 JWT；每个工作区由按需供应的隔离 Neo4j Aura 数据库支撑，也支持自带 Neo4j。
13. NAMS 的 Claude Code 注册用：claude mcp add --transport sse neo4j-agent-memory-hosted https://memory.neo4jlabs.com/mcp --header "Authorization: Bearer <nams_api_key>"；Claude Desktop 用 url + transport: sse + headers.Authorization: Bearer nams_... 的 JSON 配置。
14. 框架集成统一从 neo4j_agent_memory.integrations.<framework> 导入并安装对应 extra：LangChain（[langchain] → Neo4jAgentMemory）、Pydantic AI（[pydantic-ai] → MemoryDependency）、Google ADK（[google-adk] → Neo4jMemoryService）、AWS Strands（[strands] → context_graph_tools）、CrewAI（[crewai] → Neo4jCrewMemory）、LlamaIndex（[llamaindex] → Neo4jLlamaIndexMemory）、OpenAI Agents（[openai-agents]）、Microsoft Agent Framework（[microsoft-agent] → Neo4jMicrosoftMemory）。
15. 描述实体抽取流水线时按成本/质量从快到准排列：spaCy（快速统计 NER，最便宜）→ GLiNER（零样本、带类型 schema，GLiREL 处理关系）→ LLM 兜底（最准最贵）；富化是独立后台阶段（Wikipedia、Diffbot）；去重（v0.1.1+）用主谓匹配 + 嵌入相似度（阈值约 0.95）自动合并重复事实与偏好并更新置信度，通过 DeduplicationConfig 调优；相关配置对象：ExtractionConfig、DeduplicationConfig、MemoryIntegration、SessionStrategy。
16. 定位文案尽量逐字使用："Graph handles understanding; vector handles similarity."、"Vector stores give you recall. The graph gives you understanding."、"Three memory types, one knowledge graph."；必要时锚定 Foundation Capital 的 "AI's Trillion-Dollar Opportunity: Context Graphs" 论点，并把本项目定位为该类别的完整实现（覆盖全部三层记忆），强调上下文图与领域数据共存于同一 Neo4j 实例。
17. 使用推荐措辞：graph-native memory、context graph、three distinct memory layers、reasoning traces as first-class graph nodes、learn from past reasoning、build knowledge graphs automatically from conversations、Neo4j Labs project / experimental / community-supported。
18. 避免在已发布内容中点名具体竞品（Mem0、Zep、Letta、Cognee、Supermemory），改为围绕能力做对比；不要称其为 production-ready，不要说 officially supported 或暗示 SLA。
19. 审稿时排查常见错误：过时版本号、错误的文档 URL（应为 neo4j.com/labs/agent-memory，而非 Vercel 预览链接）、未实际运行的 API 示例、缺失 Labs 定位、与其他 Neo4j MCP 服务器（mcp-neo4j-cypher、mcp-neo4j-memory）混淆、把 NAMS 与自托管库混为一谈、对 NAMS 可用性过度承诺。
20. 引用生态项目时使用正确名称：create-context-graph（uvx create-context-graph 脚手架，文档 create-context-graph.dev）、Lenny's Podcast Memory Explorer（299 集播客旗舰演示，基于 PydanticAI）、neo4j-agent-integrations、agent-memory-tck、Microsoft Learn 集成页。
21. 示例优先指向上游仓库 examples/ 目录而非自创：lennys-memory、full-stack-chat-agent、financial-services-advisor/aws-financial-services-advisor、financial-services-advisor/google-cloud-financial-advisor、microsoft_agent_retail_assistant、domain-schemas、google_cloud_integration、google_adk_demo。
22. 画图时交叉参考 excalidraw（JSON 格式与图管理脚本）、neo4j-styleguide（Cypher 风格与品牌色）、neo4j-labs-brand（Labs 紫 #6366F1、状态徽章、免责声明措辞）等技能。
23. 新增文档按 Diataxis 框架归位：Tutorials（构建首个带记忆的 agent）、How-To Guides（实体抽取、去重、富化、集成）、Reference（配置、CLI、MCP 工具、API）、Explanation（POLE+O 模型、记忆类型、抽取流水线）。
24. 发布前过一遍权威事实清单：版本号以 PyPI 为准、文档链接指向 neo4j.com/labs/agent-memory、三种记忆类型命名正确、POLE+O 拼写一致、必要时说明 Python ≥ 3.10 与 Neo4j ≥ 5.20、README/落地页含 Labs 免责声明、已发布定位中无竞品名、突出推理记忆差异化、导入路径用 neo4j_agent_memory.integrations.<framework>（下划线 snake_case）、引用 NAMS 时与自托管库明确区分并重新核对线上端点。
25. 凭据不要硬编码；NAMS 的 bearer token 与自托管库的 Neo4j --password 属于不同层面，不可混用。

适用边界 · 注意事项

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