系统定位与设计目标

neo4j-agent-memory 是一个面向 AI 智能体的图原生（graph-native）记忆系统，其核心目标是把"对话历史"、"实体知识"与"推理轨迹"统一落到一张 Neo4j 图中，使智能体既能跨会话召回上下文，也能从自身过往的推理中学习 资料来源：README.md:1-18。系统同时提供 Python 与 TypeScript 双端 SDK，并内建与 PydanticAI、LangChain、Google ADK、Strands、CrewAI、OpenAI Agents 等框架的适配层 资料来源：README.md:14-20。所有写入操作均为 async，调用方需以 async with MemoryClient(settings) as client: 或显式 await client.connect() 管理生命周期 资料来源：examples/README.md:18-22。

三层记忆架构

系统将记忆划分为三个互补的层级，统称 short-term / long-term / reasoning：

这三层在 OpenAI Agents 适配器中通过 get_context() 被统一合并为一条系统提示词可见的上下文字符串 资料来源：src/neo4j_agent_memory/integrations/openai_agents/memory.py:50-72；在零售示例中则显式呈现为"对话历史 + 商品实体 + 过往购物推理轨迹"的复合召回 资料来源：examples/microsoft_agent_retail_assistant/README.md:120-140。社区已就此提出"为 LangGraph 提供自动记忆中间件"的需求（issue #49），用以替代由智能体显式调用 memory 的模式，目前尚未合入 资料来源：README.md 社区上下文 #49。

图模型与 POLE+O 本体

所有 long-term 实体都映射到 POLE+O 五类顶层标签（PERSON / ORGANIZATION / LOCATION / EVENT / OBJECT），并由 examples/domain-schemas/ 下的工厂类（新闻、学术、商业、娱乐、医疗、法律等）按域扩展 subtype 与关系集合 资料来源：examples/domain-schemas/README.md:25-70。实体写入时会附带嵌入向量与去重元组：await client.long_term.add_entity(...) 自 v0.1.1 起返回 (entity, dedup_result)，调用方需用 _, _ = await ... 显式解包 资料来源：examples/README.md:24-27。

在 v0.4.0 引入的 NAMS（Neo4j Agent Memory Service）后端上，图模式不再是写死的 Cypher，而是由 *ontology*（一个版本化、带 validation_mode 的类型化 schema）驱动：每个 EntityTypeDef 显式声明 poleType，每个 PropertyDef 携带 type / required / unique / enum 约束，关系类型也由 RelationshipDef 类型化 资料来源：src/neo4j_agent_memory/nams/ontology.py:60-110。同一组模型在 TypeScript SDK 中以 OntologyClient 暴露，并通过 /ontologies REST 端点完成克隆、激活、版本化与结构化 diff 资料来源：typescript/src/ontology/index.ts:1-90。

flowchart LR
    subgraph Client["MemoryClient (Python / TS)"]
        ST[Short-Term]
        LT[Long-Term]
        RS[Reasoning]
    end
    ST -->|messages| S[(Session / Message)]
    LT -->|entities & relations| K[(Entity · POLE+O)]
    RS -->|steps & tool calls| T[(ReasoningTrace)]
    K -. :TOUCHED .-> T
    S -. sem search .-> K
    T -. provenance .-> K

托管后端 NAMS 与自托管切换

v0.4.0 把 MemorySettings(backend="nams", ...) 作为纯加性选项引入，调用方只需在配置阶段选择本地 bolt 直连 Neo4j 还是托管 REST 服务，面向 MemoryClient 的业务代码无需改动 资料来源：README.md 社区上下文 v0.4.0。NAMS 端点以 *_ontology 子路径对外，并显式声明"这些路由不在 staging OpenAPI 中，是通过实测验证的"——这意味着客户端代码（含 TS SDK）必须把这些路径当作受支持的隐式契约 资料来源：typescript/src/ontology/index.ts:10-20。TypeScript 端通过 RestTransport 的 snakeBody 标志把 ontology 请求体保持为 snake_case JSON 以匹配服务端 资料来源：typescript/src/ontology/index.ts:130-160。

审计追溯与推理可解释性

系统的设计亮点之一是 :TOUCHED 审计边——每次推理步骤都会显式指向被它"触碰"过的实体，从而既能解释"该结论来自哪段历史"，也能支撑实体级 provenance 视图 资料来源：README.md:6-12；ReasoningMemory 进一步把 explain 行为作为"白银层"包装方法，在 hosted-native 模式下则提供更扁平的"按 conversation 取 step"接口 资料来源：typescript/src/reasoning/index.ts:1-50。社区同时讨论了记忆衰减（issue #42：在检索阶段加入时间感知 re-ranker）与多租户可见性（issue #13：把程序性记忆标为组织内公开），这两项尚未合入，但与当前的 POLE+O 图模型天然兼容——衰减可作为长期检索器的后处理步骤，公开/私有则可作为 Entity 上的访问控制属性 资料来源：README.md 社区上下文 #42 #13。

常见使用模式

• 异步一次性上下文召回：await client.get_context(query=..., session_id=..., include_short_term=True, include_long_term=True, include_reasoning=True) 资料来源：src/neo4j_agent_memory/integrations/openai_agents/memory.py:55-72。
• 批量转写导入：通过 client.buffered.submit(...) 实现 fire-and-forget 写入，适合 Lenny Podcast 类的转写灌入（issue #11 也提出过 CLI 化批处理需求） 资料来源：README.md:8-10。
• 采纳已有图：生产环境已有 Neo4j 图时，使用 client.schema.adopt_existing_graph(...) 在不破坏既有数据的前提下叠加记忆层 资料来源：README.md:8-10。

See Also

• MCP Tools Reference — 16 工具的 MCP server 详细说明
• Provider Migration Guide — OpenAI / Anthropic / Bedrock / Vertex AI / LiteLLM 适配说明
• Examples Index — 旗舰 demo 与单功能小例的入口
• Community Issue #49 — LangGraph 中间件与自动记忆存取
• Community Issue #42 — 检索阶段记忆衰减与时间重排

后端（NAMS vs Bolt）、配置与 SDK 初始化

概述

neo4j-agent-memory 通过统一的 MemoryClient 抽象，向应用层暴露短期会话、长期实体 / 偏好 / 事实、推理轨迹等能力。底层实现可由 MemorySettings(backend=...) 在两种后端之间切换：

• Bolt 后端：客户端直接通过 Bolt 协议连到本地或自管的 Neo4j 数据库，所有读写下沉到自有集群。
• NAMS 后端（Neo4j Agent Memory Service）：客户端把 MemoryClient 的所有调用作为 HTTP 请求，转发给 Neo4j Labs 托管的 REST 服务。

两种后端共享同一份应用代码。backend="nams" 在 v0.4.0 中作为可选项加入；现有基于 v0.3.x 编写、跑在 Bolt 上的代码无需修改即可继续运行。该变化被官方描述为“完全叠加”（purely additive）。资料来源：README.md

架构总览

flowchart LR
    App[Agent / 应用] --> MC[MemoryClient]
    MC -->|backend=bolt| BC[graph/client.py<br/>BoltDriver]
    BC --> Neo4j[(自管 Neo4j)]
    MC -->|backend=nams| NC[nams/client.py<br/>NamsClient]
    NC --> HT[nams/transport.py<br/>HttpTransport]
    HT -->|HTTPS + Bearer| NAMS[(NAMS 托管服务)]
    MS[MemorySettings] -.配置.-> MC
    Auth[nams/auth.py] -.API Key.-> NC

Bolt 后端（自管 Neo4j）

Bolt 后端是项目的默认形态。MemoryClient 在该模式下通过 graph/client.py 中的驱动直接与 Neo4j 通信：写入直接落到图数据库，查询由客户端拼装 Cypher 再下发。Pydantic 风格的领域对象在客户端与图节点之间互转。该模式适合以下场景：

• 数据需要完全驻留在自有环境，满足合规与数据主权要求；
• 团队已维护 Neo4j 集群，希望复用既有的运维、备份与监控链路；
• 需在客户端层面编写自定义 Cypher、扩展 POLE+O 之外的实体类型或推理节点。

资料来源：README.md、src/neo4j_agent_memory/graph/client.py

NAMS 后端（托管 REST 服务）

NAMS 后端由 src/neo4j_agent_memory/nams/ 子包实现。NamsClient 通过 HttpTransport 把 Pydantic 模型序列化为 JSON 提交给托管服务。关键约束与约定：

• 端点并未完全公开在 OpenAPI 中，部分路由（如 */ontologies）的负载与响应需按经验实现，并通过 snakeBody 透传 snake_case 字段。资料来源：src/neo4j_agent_memory/nams/ontology.py
• 身份由 nams/auth.py 中的 MEMORY_API_KEY（形如 nams_xxxxxxxxxxxxxxxx）承载，调用时通过 Authorization: Bearer ... 头发送。资料来源：src/neo4j_agent_memory/nams/auth.py、[examples/README.md]()
• JSON 编解码统一通过 _serialization.py 处理：UUID → str、datetime → ISO 8601、None 字段从出站负载中剔除，由服务端默认值兜底。资料来源：src/neo4j_agent_memory/nams/_serialization.py
• 顶层导出集中在 nams/__init__.py，包括 NamsClient、NamsOntology、OntologyDocument、MigrationJob 等 v0.5 阶段符号。资料来源：src/neo4j_agent_memory/nams/__init__.py

配置与 SDK 初始化

MemorySettings 是唯一的配置入口。backend 字段决定运行时走 Bolt 还是 NAMS；embedding 与 llm 字段控制抽取向量与补全模型，二者既支持简写 provider 字符串（如 "anthropic/claude-3-5-sonnet-latest"、"BAAI/bge-small-en-v1.5"），也支持显式 Provider 实例；原生适配器覆盖 OpenAI、Anthropic、Bedrock、Vertex AI、sentence-transformers，其余 100+ 提供商由 LiteLLM 兜底。资料来源：README.md、src/neo4j_agent_memory/llm/factory.py

NAMS 模式下，凭证与端点通常通过环境变量注入：

export MEMORY_API_KEY=nams_xxxxxxxxxxxxxxxx
export MEMORY_ENDPOINT=https://nams.staging.neo4j.io

随后在脚本中以异步上下文管理器实例化客户端：

from neo4j_agent_memory import MemoryClient, MemorySettings

settings = MemorySettings(backend="nams", api_key=..., endpoint=...)
async with MemoryClient(settings) as client:
    entity, dedup = await client.long_term.add_entity(...)

add_entity 等长期记忆调用自 v0.1.1 起返回 (entity, dedup_result) 元组，调用方需要解包；其余方法遵循相同的 await 异步约定。资料来源：examples/README.md

选型建议与社区关注点

Bolt 后端由用户自管 Neo4j，鉴权依赖数据库账号密码，水平扩展受限于自建集群规模；NAMS 后端由服务商负责弹性伸缩，鉴权统一收敛到 MEMORY_API_KEY。社区中关于自动记忆读写中间件（issue #49，LangGraph Middleware）、记忆衰减重排序（issue #42）、多租户 / 组织级安全（issue #13）的讨论，是后端无关的应用层话题，但它们在 NAMS 模式下更接近一等公民能力，应结合所选后端评估落地路径。此外，OPENAI_API_KEY 等模型凭证在两种后端下都需要在启动前就绪，缺失时建议显式 fail-fast 而不是静默回退。资料来源：README.md、examples/README.md

See Also

• Use NAMS 使用指南
• Bolt vs NAMS 后端选型说明
• Provider 迁移指南
• examples/README.md

集成总览

agent-memory 提供三种"接入路径"，让不同技术栈的代理（agent）应用都能复用其三层记忆（短期会话、长期实体、推理轨迹）能力：（1）面向通用 LLM 代理的 MCP Server；（2）面向主流代理框架的 语言绑定；（3）面向真实业务场景的 参考应用。

仓库的 TypeScript 入口将所有子客户端统一导出，包含 ShortTermMemory、LongTermMemory、ReasoningMemory、QueryConsole、AuthClient 与 OntologyClient 等，开发者既能走高级 MemoryClient 门面，也能直接构造某个子模块做精细化调用。资料来源：typescript/src/index.ts:1-50

Python 端 neo4j_agent_memory.nams 包在 v0.5 之后扩展了 NAMS 后端支持，并暴露 NamsOntology 等类型化模型，确保两侧语言的 API 形态在托管与本地 bolt 模式下保持一致。资料来源：src/neo4j_agent_memory/nams/\_\_init\_\_.py:1-30

MCP Server

README 明确指出项目随附一个 MCP server，提供 16 个工具，覆盖会话历史、实体详情、图谱导出、关系创建、推理轨迹、观察值（observation）以及只读 Cypher 等能力。资料来源：README.md:1-15

TypeScript 端的 MCP 样例独立打包，使用官方 @modelcontextprotocol/sdk 1.x，并以 file:../.. 引用本地构建产物，开发者可在 typescript/examples/mcp/ 下用 pnpm start 启动该服务端。资料来源：typescript/examples/mcp/package.json:1-13

社区 Issue #49 提议为 LangGraph 增加 Middleware，把记忆读写从"由 agent 显式调用"改为"在 LLM 调用前后自动触发"，与 MCP server 的工具化暴露形成互补——MCP 提供被动工具接口，而 Middleware 提供主动拦截层。资料来源：README.md:1-15（结合社区讨论 #49）

框架集成

LangChain（JS）

Neo4jChatMessageHistory 将 MemoryClient 适配为 LangChain JS 的 BaseChatMessageHistory 形态，按 human/ai/system 与 user/assistant/system 的双向映射把消息写入短期记忆。资料来源：typescript/src/integrations/langchain.ts:1-60

Python 端的 LangChain 集成（integrations/langchain/memory.py 与 retriever.py）则提供 Neo4jChatMessageHistory 与 Neo4jEntityRetriever，常用于把长期实体作为 retriever 嵌入 RAG 链路。

Microsoft Agent Framework

Neo4jMicrosoftMemory 把 BaseContextProvider 与 BaseHistoryProvider 合并为一个统一接口，可同时挂到 chat_client.as_agent(context_providers=[...]) 上，让 agent 自动获得上下文注入与历史持久化。资料来源：src/neo4j_agent_memory/integrations/microsoft_agent/memory.py:1-90

OpenAI Agents SDK

OpenAI Agents 适配器在保存消息时支持 extract_entities 与 generate_embedding 开关，并把工具调用与 tool_call_id 写入元数据，使代理在多步调用中能够正确回写消息。资料来源：src/neo4j_agent_memory/integrations/openai_agents/memory.py:1-90

README 顶部列出的官方支持框架还包括 Pydantic AI、Google ADK、Strands、CrewAI，社区 Issue #49 中的 LangGraph Middleware 是目前最受关注的待补齐适配。资料来源：README.md:1-15

参考应用

examples/ 目录下沉淀了三类应用：旗舰演示、领域 schema 与多代理金融合规。资料来源：examples/README.md:1-40

领域 schema（domain-schemas/）则给出 podcast、新闻、学术、商业、娱乐、医疗、法律等 7 套工厂化 POLE+O 模板，开发者可按业务直接套用并按需裁剪。资料来源：examples/domain-schemas/README.md:1-30

社区待办与边界

• #11 Add CLI：当前缺少批量导入、基准评测、样本加载的官方命令行工具，CLI 相关需求被合并到未来的客户端工具中讨论。
• #13 Security / Auth：现有 AuthClient（见 typescript/src/index.ts）仅覆盖 API Key/Token 维度，跨用户"公共/私有"记忆作用域（如程序性记忆共享）尚未抽象。
• #42 记忆衰减：retriever 尚未提供时间衰减重排器，目前记忆新鲜度依赖向量相似度排序。

See Also

• 主页：README.md
• 配置与后端：MemoryClient 入门（v0.4.0 NAMS）
• 本体系统：Ontology / NAMS Ontology
• 示例索引：examples/README.md

记忆操作、提取流水线与路线图主题

概述

neo4j-labs/agent-memory 是一套以 Neo4j 为长期存储后端的智能体记忆库。它把记忆拆成 短期（对话历史）、长期（实体 / 偏好 / 事实） 与 推理（trace / step） 三层，并提供 多阶段实体提取流水线、后台富集、POLE+O 本体 与 MCP 工具 / 框架中间件 集成。项目同时维护 Python 与 TypeScript 双 SDK，从 v0.4.0 起新增 NAMS（Neo4j Agent Memory Service） 后端，开发者可在 MemorySettings(backend="nams" | "bolt") 之间无侵入切换 README.md。

资料来源：README.md:1-30

记忆操作分层

MemoryClient 通过三个命名空间暴露 CRUD / 检索能力，社区示例普遍以 async with MemoryClient(settings) as client: 模式管理生命周期 examples/README.md:1-30。

short_term 负责把对话消息落图并附带 tool_calls、tool_call_id 等元数据 src/.../openai_agents/memory.py:1-60。long_term 在 TypeScript SDK 中以"桥接方法 + Volume 5 托管原生方法"两层 API 暴露实体反馈、历史追溯、按 ID 合并与图视图 typescript/src/long-term/index.ts:1-30。reasoning 命名空间同样提供托管平铺方法（step 直接隶属于 conversation），并附 explain / provenance 视图用于审计 typescript/src/reasoning/index.ts:1-20。

提取流水线

提取阶段是构建长期记忆的核心，仓库在 README 与 domain-schemas 示例中均强调 多阶段 + 可插拔 设计：先由 spaCy / GLiNER / LLM 进行命名实体识别，再由 GLiREL 完成关系抽取，最后在后台异步执行 Wikipedia / Diffbot 富集 README.md:1-30。

资料来源：README.md:1-30、 examples/domain-schemas/README.md:1-60

本体层采用 POLE+O（Person / Organization / Location / Event / Object）字符串标签而非枚举，便于扩展领域子类（subtype），示例涵盖 poleo（调查分析）、podcast、news、scientific、business、entertainment、medical、legal 等域 examples/domain-schemas/README.md:1-60。在 NAMS 后端中，本体被建模为可版本化文档，包含 EntityTypeDef、RelationshipDef、PropertyDef，并支持创建 / 克隆 / 设为主线 / 删除等生命周期操作 src/.../nams/ontology.py:1-60、 typescript/src/ontology/index.ts:1-60。

flowchart LR
  A[原始文本] --> B[阶段1 NER<br/>spaCy / GLiNER / LLM]
  B --> C[阶段2 关系抽取<br/>GLiREL]
  C --> D[POLE+O 实体/关系<br/>入库 Neo4j]
  D --> E[后台富集<br/>Wikipedia / Diffbot]
  E --> F[长期记忆<br/>Entity / Preference / Fact]

框架集成与中间件

为减少业务侧对"何时调用记忆"的判断成本，仓库提供两类集成：

• 显式适配器：Neo4jChatMessageHistory（LangChain JS）、Neo4jMicrosoftMemory（封装 BaseContextProvider + BaseHistoryProvider，可直接挂到 Microsoft Agent 上）typescript/src/integrations/langchain.ts:1-40、 src/.../microsoft_agent/memory.py:1-60。
• 透明中间件：agentMemoryMiddleware(client, { conversationId, userId, includeContext }) 在每次 generateText 调用前注入三段式上下文（reflections + observations + recent messages），调用后回写用户输入与助手输出，必要时懒创建 conversation typescript/src/middleware/vercel-ai.ts:1-40。

社区在 issue #49 中提出 LangGraph Middleware 的等价需求，希望在 LLM 调用前后自动完成记忆的存取，这与 Vercel AI SDK 中间件的设计思路一致 README.md:1-30。

路线图相关议题

结合社区高频议题与已发布能力，记忆库的下一步演进聚焦四个方向：

1. 时间衰减与重排序：issue #42 建议在检索阶段引入"时间重排序器"，让近期记忆获得更高权重，同时识别并淘汰异常记忆。README 中提到的 GLiREL 关系抽取与缓冲写入可作为前置信号 README.md:1-30。
2. 多租户与安全 / 授权：issue #13 区分"个人记忆"与"组织级公共记忆"（如程序性 SOP），需配合 user_identifier= 多租户作用域与受控的可见性策略 README.md:1-30。
3. CLI 与批处理工具：issue #11 提出转录批量入库、跨 schema / 模型基准测试、样例加载等命令入口，目前主要由 examples/ 下的脚本承担，尚未统一 CLI examples/README.md:1-30。
4. 托管后端持续完善：v0.4.0 引入的 NAMS REST 后端在配置层是纯增量变更；TypeScript 侧的 snakeBody 路由与 NotSupportedError 处理仍处于与开放 API 对齐阶段 typescript/src/ontology/index.ts:1-20、 src/.../nams/ontology.py:1-30。

资料来源：README.md:1-30、 examples/README.md:1-30

常见失败模式

• OPENAI_API_KEY 缺失导致静默失败：issue #7 反馈 Lenny Podcast 示例因未设 key 而异常，应在启动期 fail-fast 并显式提示 examples/README.md:1-30。
• 方法签名漂移：v0.1.1 后 add_entity 返回 (entity, dedup_result) 元组，旧代码若按单值解包会触发 ValueError examples/README.md:1-30。
• 后端能力差异：NAMS 与 bolt 后端并非完全等价，例如 client.ontology 托管端点不在 OpenAPI 规范内，TypeScript SDK 对其启用 snakeBody 旁路并对未实现能力抛出 NotSupportedError typescript/src/ontology/index.ts:1-20。

See Also

• README.md
• examples/README.md
• examples/domain-schemas/README.md
• typescript/src/middleware/vercel-ai.ts
• src/neo4j_agent_memory/nams/ontology.py

Pitfall Log / 踩坑日志

项目：neo4j-labs/agent-memory

摘要：发现 20 个潜在踩坑项，其中 3 个为 high/blocking；最高优先级：安装坑 - 来源证据：Build #42's decay as re-ranking over a bitemporal, invalidate-not-delete store。

1. 安装坑 · 来源证据：Build #42's decay as re-ranking over a bitemporal, invalidate-not-delete store

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Build #42's decay as re-ranking over a bitemporal, invalidate-not-delete store
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/neo4j-labs/agent-memory/issues/138 | 来源类型 github_issue 暴露的待验证使用条件。

2. 安装坑 · 来源证据：Support memory decay in memory search retrievers

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Support memory decay in memory search retrievers
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/neo4j-labs/agent-memory/issues/42 | 来源类型 github_issue 暴露的待验证使用条件。

3. 维护坑 · 来源证据：Long-term recall is not isolation-enforced per user (Entity/Fact are global; omitting `user_identifier` returns another…

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Long-term recall is not isolation-enforced per user (Entity/Fact are global; omitting user_identifier returns another user's data)
• 对用户的影响：可能影响升级、迁移或版本选择。
• 证据：community_evidence:github | https://github.com/neo4j-labs/agent-memory/issues/137 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

4. 安装坑 · 来源证据：If short-term memory is processed multiple times, Message-to-Entity links are skipped for existing extracted entities

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：If short-term memory is processed multiple times, Message-to-Entity links are skipped for existing extracted entities
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/neo4j-labs/agent-memory/issues/131 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

5. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | https://github.com/neo4j-labs/agent-memory | host_targets=mcp_host, claude, chatgpt

6. 配置坑 · 来源证据：[Python SDK] NamsConfig requires endpoint with /v1 suffix — quick-start docs use base URL without it

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[Python SDK] NamsConfig requires endpoint with /v1 suffix — quick-start docs use base URL without it
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/neo4j-labs/agent-memory/issues/129 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

7. 配置坑 · 来源证据：[TypeScript SDK] EntityTypeDef.poleType typed as string — invalid values pass compile-time but fail at runtime with 422

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[TypeScript SDK] EntityTypeDef.poleType typed as string — invalid values pass compile-time but fail at runtime with 422
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/neo4j-labs/agent-memory/issues/141 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

8. 配置坑 · 来源证据：false acks

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：false acks
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/neo4j-labs/agent-memory/issues/140 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

9. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/neo4j-labs/agent-memory | README/documentation is current enough for a first validation pass.

10. 维护坑 · 来源证据：[Python SDK] record_tool_call() and get_session_traces() crash with ValidationError — server returns status='completed'…

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：[Python SDK] record_tool_call() and get_session_traces() crash with ValidationError — server returns status='completed' not in ToolCallStatus enum
• 对用户的影响：可能阻塞安装或首次运行。
• 证据：community_evidence:github | https://github.com/neo4j-labs/agent-memory/issues/128 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

11. 维护坑 · 来源证据：[TypeScript SDK] getConversation and getContext return silent 200 for non-existent IDs instead of throwing NotFoundError

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：[TypeScript SDK] getConversation and getContext return silent 200 for non-existent IDs instead of throwing NotFoundError
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/neo4j-labs/agent-memory/issues/124 | 来源类型 github_issue 暴露的待验证使用条件。

12. 维护坑 · 来源证据：[TypeScript SDK] getEntity throws TransportError instead of NotFoundError for missing entities

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：[TypeScript SDK] getEntity throws TransportError instead of NotFoundError for missing entities
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/neo4j-labs/agent-memory/issues/125 | 来源类型 github_issue 暴露的待验证使用条件。

13. 维护坑 · 来源证据：[TypeScript SDK] searchMessages — sessionId typed as optional but required at runtime on hosted service

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：[TypeScript SDK] searchMessages — sessionId typed as optional but required at runtime on hosted service
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/neo4j-labs/agent-memory/issues/126 | 来源类型 github_issue 暴露的待验证使用条件。

14. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/neo4j-labs/agent-memory | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/neo4j-labs/agent-memory | no_demo; severity=medium

16. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/neo4j-labs/agent-memory | no_demo; severity=medium

17. 安全/权限坑 · 来源证据：[Bug/Integration] `Neo4jMemoryService` (Google ADK) is incompatible with NAMS backend + v0.4 documentation Mismatches

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Bug/Integration] Neo4jMemoryService (Google ADK) is incompatible with NAMS backend + v0.4 documentation Mismatches
• 对用户的影响：可能阻塞安装或首次运行。
• 证据：community_evidence:github | https://github.com/neo4j-labs/agent-memory/issues/130 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

18. 安全/权限坑 · 来源证据：[TypeScript + Python SDK] Methods unavailable on hosted service throw NotSupportedError with no compile-time warning

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[TypeScript + Python SDK] Methods unavailable on hosted service throw NotSupportedError with no compile-time warning
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/neo4j-labs/agent-memory/issues/127 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

19. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/neo4j-labs/agent-memory | issue_or_pr_quality=unknown

20. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/neo4j-labs/agent-memory | release_recency=unknown