agentic_huge_data_base / wiki
页面 Cognee · 14.3 智能体记忆装饰器·DeepWiki 中文全文译文
DeepWiki 中文译文 / Cognee / 14.3

14.3 · 智能体记忆装饰器（Agent Memory Decorator）

记忆管道与知识图谱构建 · 聚焦本章的模块关系、源码依据与实现要点。

项目Cognee 章节14.3 状态全文译文 模块记忆与上下文、测试、发布与运维、检索、召回与索引、界面与交互
项目要点页2.5 参考项目 项目章节目录Cognee DeepWiki 原始章节Agent Memory Decorator 上一章14.2 下一章15
源码线索
  • cognee-mcp/src/strip_vectors.py
  • cognee/infrastructure/llm/LLMGateway.py
  • cognee/modules/agent_memory/__init__.py
  • cognee/modules/agent_memory/decorator.py
  • cognee/modules/agent_memory/runtime.py
  • cognee/tests/integration/modules/agent_memory/test_agent_memory_integration.py
  • cognee/tests/test_agent_memory_e2e.py
  • cognee/tests/unit/modules/agent_memory/test_agent_memory.py
  • examples/guides/agent_memory_quickstart.py
  • examples/guides/recall_core.py
模块标签
  • 记忆与上下文
  • 测试、发布与运维
  • 检索、召回与索引
  • 界面与交互
  • 认证、权限与安全

章节正文

智能体记忆装饰器

原始 DeepWiki 页面https://deepwiki.com/topoteretes/cognee/14.3-agent-memory-decorator

智能体记忆装饰器（代理记忆装饰器）

相关源文件

本章引用的主要源码文件：

  • cognee-mcp/src/strip_vectors.py
  • cognee/infrastructure/llm/LLMGateway.py
  • cognee/modules/agent_memory/__init__.py
  • cognee/modules/agent_memory/decorator.py
  • cognee/modules/agent_memory/runtime.py
  • cognee/tests/integration/modules/agent_memory/test_agent_memory_integration.py
  • cognee/tests/test_agent_memory_e2e.py
  • cognee/tests/unit/modules/agent_memory/test_agent_memory.py
  • examples/guides/agent_memory_quickstart.py
  • examples/guides/recall_core.py
  • examples/guides/temporal_recall.py

@agent_memory 装饰器是 Cognee 中的高级工具，旨在为 AI 代理提供持久化记忆和自动化可观测性。它在函数执行前管理从知识图谱中检索相关上下文，并确保执行轨迹（输入、输出和错误）被保存回记忆系统中 cognee/modules/agent_memory/decorator.py:23-49。

核心组件

AgentMemoryConfig

AgentMemoryConfig 数据类定义了特定装饰函数的记忆系统行为。它在装饰时被校验和规范化，以确保 session_memory_last_n 和 memory_top_k 等参数在有效范围内 cognee/modules/agent_memory/runtime.py:28-46，cognee/modules/agent_memory/runtime.py:98-116。

参数类型描述
with_memorybool如果为 True，则在调用函数前从 Cognee 知识图谱检索上下文 cognee/modules/agent_memory/runtime.py:31。
with_session_memorybool启用从会话缓存中检索最近的交互历史 cognee/modules/agent_memory/runtime.py:32。
save_session_tracesbool如果为 True，则将函数调用详情（轨迹）持久化到会话管理器 cognee/modules/agent_memory/runtime.py:33。
memory_query_fixedstr用于查询记忆系统的静态字符串 cognee/modules/agent_memory/runtime.py:34。
memory_query_from_methodstr函数参数的名称，其值将用作记忆查询 cognee/modules/agent_memory/runtime.py:35。
session_idstr代理会话的唯一标识符，用于隔离轨迹历史 cognee/modules/agent_memory/runtime.py:40。
persist_session_trace_afterint交互次数阈值，超过此次数后会话轨迹将被移至长期记忆（图数据库） cognee/modules/agent_memory/runtime.py:44。
AgentScope

AgentScope 表示已授权的数据集上下文，用于 Cognee 支持的记忆检索。它将 User 链接到特定的 dataset_id 和 dataset_name cognee/modules/agent_memory/runtime.py:50-56。

AgentMemoryContext

每次调用时的执行状态，用于在检索、包装调用和轨迹持久化之间共享数据。它存储在名为 _agent_memory_context_var 的 contextvars.ContextVar 中，以确保在整个异步执行链中可访问 cognee/modules/agent_memory/runtime.py:59-75。

来源：cognee/modules/agent_memory/runtime.py:28-75，cognee/modules/agent_memory/decorator.py:23-41，cognee/modules/agent_memory/runtime.py:98-116

执行流程

该装饰器包装异步函数，并管理基于 contextvars 的生命周期，以确保即使在深层调用栈中也能访问记忆上下文 cognee/modules/agent_memory/decorator.py:86-115。

记忆注入过程
  1. 作用域解析：系统通过 resolve_agent_user 识别 User，通过 resolve_agent_dataset_scope 识别 AgentScope cognee/modules/agent_memory/decorator.py:91-93。
  2. 上下文检索：如果启用了 with_memory 或 with_session_memory，则调用 retrieve_memory_context 获取图数据和会话历史 cognee/modules/agent_memory/decorator.py:104。
  3. 大语言模型（LLM）注入：当代理调用 LLMGateway.acreate_structured_output 时，_inject_agent_memory 辅助函数会自动将检索到的记忆上下文前置到 text_input 中 cognee/infrastructure/llm/LLMGateway.py:14-21，cognee/infrastructure/llm/LLMGateway.py:65。
  4. 轨迹持久化：函数执行完成（或失败）后，调用 persist_trace 保存 AgentMemoryContext 状态 cognee/modules/agent_memory/decorator.py:115。
数据流图：记忆注入

此图展示了装饰器如何将高级函数调用桥接到低级大语言模型（LLM）网关。

"自然语言空间"到"代码实体空间"

Cognee · 数据流图：记忆注入 · 图 1
Cognee · 数据流图：记忆注入 · 图 1

来源：cognee/modules/agent_memory/decorator.py:87-115，cognee/infrastructure/llm/LLMGateway.py:14-21，cognee/infrastructure/llm/LLMGateway.py:59-65，cognee/modules/agent_memory/runtime.py:74-81

代理轨迹与持久化

轨迹捕获了代理调用的生命周期。它们由 SessionManager 管理，可以作为图节点持久化，也可以存储在会话缓存中 cognee/modules/agent_memory/decorator.py:115，cognee/modules/agent_memory/runtime.py:69-71。

轨迹状态

执行轨迹捕获以下内容：

  • origin_function：装饰函数的 __qualname__ cognee/modules/agent_memory/runtime.py:62。
  • method_params：传递给函数的参数字典，通过 build_method_params 构建 cognee/modules/agent_memory/runtime.py:64。
  • status：从 "running" 转换为 "success" 或 "error" cognee/modules/agent_memory/runtime.py:70。
  • method_return_value：包装函数返回的结果 cognee/modules/agent_memory/runtime.py:69。
  • error_message：捕获到的任何异常的字符串表示 cognee/modules/agent_memory/runtime.py:71。
轨迹持久化图

此图映射了保存轨迹所涉及的代码实体。

"代码实体空间"到"持久化层"

Cognee · 轨迹持久化图 · 图 2
Cognee · 轨迹持久化图 · 图 2

来源：cognee/modules/agent_memory/decorator.py:113-115，cognee/modules/agent_memory/runtime.py:59-72，cognee/infrastructure/session/session_manager.py，cognee/tests/integration/modules/agent_memory/test_agent_memory_integration.py:142-168

安全与权限

该装饰器通过在执行前解析 User 和 AgentScope 来强制实施多租户 cognee/modules/agent_memory/decorator.py:91-93。

  • 用户解析：resolve_agent_user 从配置中获取用户，或默认使用系统默认用户 cognee/modules/agent_memory/runtime.py:12，cognee/modules/agent_memory/decorator.py:91。
  • 数据集权限：如果启用了 with_memory，系统会通过 resolve_agent_dataset_scope 验证用户对 dataset_name 拥有必要的权限 cognee/modules/agent_memory/runtime.py:14-15，cognee/modules/agent_memory/decorator.py:93。
  • 校验：无效配置（例如同时提供 memory_query_fixed 和 memory_query_from_method）会导致 CogneeValidationError cognee/modules/agent_memory/runtime.py:177-181。
  • 权限约束：对于共享记忆检索，用户通常需要对数据集同时拥有读写权限 cognee/tests/test_agent_memory_e2e.py:99-102。

来源：cognee/modules/agent_memory/runtime.py:12-20，cognee/modules/agent_memory/decorator.py:75-84，cognee/tests/test_agent_memory_e2e.py:99-102