长期记忆

长期记忆跨会话、跨时间保存重要信息，包括用户偏好、任务历史、知识要点或长期状态。短期记忆按会话恢复历史，长期记忆按查询召回相关内容，而长期记忆让智能体在不同会话之间也能记住事实。为什么需要它：

支持跨会话的连续对话体验；
让智能体在多次交互中保留学习成果和用户特定信息；
减少重复询问，提升满意度与效率；
支撑长期策略优化，如个性化推荐或任务追踪。

统一入口：`LongTermMemory`

无论使用哪种后端，均通过统一的 veadk.memory.long_term_memory.LongTermMemory 接入。它可直接作为智能体的记忆服务，并根据 backend 选择存储后端。

from veadk.memory.long_term_memory import LongTermMemory

ltm = LongTermMemory(backend="viking", app_name="ltm_demo")

参数

参数	类型	默认值	说明
`backend`	`"local" \| "opensearch" \| "redis" \| "viking" \| "mem0" \| "openviking" \| "tos_context"`	`"opensearch"`	选择后端。`viking_mem` 已废弃，自动转为 `viking`
`backend_config`	`dict`	`{}`	后端专用配置；若不含 `index`，会用 `index` 或 `app_name` 补齐
`top_k`	`int`	`5`	检索时返回最相似的片段数量
`index`	`str`	`""`	存储记忆所用的索引/集合名。不提供 backend_config 时回退到 `app_name`，再为空则用 `default_app`；提供配置字典时应设置非空 index
`app_name`	`str`	`""`	拥有该记忆的应用名，常用作数据隔离与 `index` 的回退值
`user_id`	`str`	`""`	已废弃，仅为向后兼容保留

向量类后端（local、opensearch、redis）会对记忆做向量化，需要安装扩展依赖并配置 embedding 模型。viking、mem0、openviking 与 tos_context 使用外部服务，无需本地 embedding。

选择后端

调试可以用 local；生产环境可根据已有云服务和数据管理要求选择 viking、mem0 或 tos_context

后端	存储	依赖	适用场景	文档
`local`	内存向量索引	`extensions` + embedding	本地调试	本地内存
`viking`	VikingDB 记忆库（托管）	火山引擎账号	托管记忆	VikingDB
`mem0`	Mem0 记忆库（托管）	Mem0 API Key	托管记忆	Mem0
`opensearch`	OpenSearch 向量库	OpenSearch + embedding	自建向量检索	OpenSearch
`redis`	Redis 向量库	Redis(RediSearch) + embedding	自建向量检索	Redis
`openviking`	OpenViking 用户记忆	OpenViking 服务	实体、事件与偏好记忆	OpenViking
`tos_context`	TOS ContextBucket（托管）	火山引擎账号与 TOS SDK `>=2.9.4b1`	托管记忆推理与按用户隔离	TOS ContextBucket

绑定到智能体

把 long_term_memory 传给 Agent 后，智能体会自动获得 load_memory 工具，可在运行时检索过往会话。

from veadk import Agent, Runner
from veadk.memory.long_term_memory import LongTermMemory

APP_NAME = "ltm_demo"
ltm = LongTermMemory(backend="viking", app_name=APP_NAME)

root_agent = Agent(
    name="ltm_agent",
    instruction="回答用户问题。如果答案可能在过往对话里，使用 `load_memory` 工具检索。",
    long_term_memory=ltm,
)
runner = Runner(agent=root_agent, app_name=APP_NAME)

记忆管理

写入：`add_session_to_memory`

会话结束或达到某个节点时，调用异步方法 add_session_to_memory 把会话持久化。LongTermMemory 会根据自动保存策略过滤事件，默认只保留用户文本事件以提升检索质量；你也可以通过 auto_save_memory_policy 参数自定义过滤规则，再交给后端写入。

completed_session = await runner.session_service.get_session(
    app_name=APP_NAME, user_id=USER_ID, session_id=SESSION_ID
)
await ltm.add_session_to_memory(completed_session)

add_session_to_memory 接受可选的 auto_save_memory_policy 关键字参数，用于覆盖默认过滤策略：

from veadk.memory import MemoryAutoSavePolicy

await ltm.add_session_to_memory(
    completed_session,
    auto_save_memory_policy=MemoryAutoSavePolicy(preset="all"),
)

检索：`search_memory`

除了智能体运行时通过 load_memory 自动检索，你也可以直接调用异步方法 search_memory 做语义搜索，用于调试或自定义 RAG：

response = await ltm.search_memory(
    app_name=APP_NAME,
    user_id=USER_ID,
    query="favorite project",
)
print(response.memories)

get_user_profile(user_id) 仅 viking 后端支持，用于获取用户画像；其他后端会返回空字符串。

自动保存会话

在初始化 Agent 时开启 auto_save_session=True 并配置好长期记忆，VeADK 会自动把会话写入长期记忆，无需手动调用 add_session_to_memory。

from veadk import Agent
from veadk.memory.long_term_memory import LongTermMemory

agent = Agent(
    name="ltm_agent",
    auto_save_session=True,
    long_term_memory=LongTermMemory(backend="viking", app_name="ltm_demo"),
)

自动保存会在运行结束回调中检查阈值，VeADK 提供 MIN_MESSAGES_THRESHOLD 与 MIN_TIME_THRESHOLD 两个环境变量自定义保存周期：默认在累计 10 条 event 或间隔 60 秒时触发保存；此外，当切换 session_id 并发起新问答时，VeADK 会自动把上一个会话写入长期记忆。自动保存采用增量写入：每次触发保存时只持久化自上次保存以来新增的事件，而非整个会话。如果两次保存之间没有新事件，则跳过写入。

控制保存内容：`auto_save_memory_policy`

Agent 接受 auto_save_memory_policy 参数，用于控制自动保存时哪些事件会被写入长期记忆。该参数同样作为 auto_save_memory_policy 关键字参数传递给 add_session_to_memory。参数类型为 MemoryAutoSavePolicyInput，接受以下形式之一：

字符串预设值："default"、"all" 或 "custom"；
MemoryAutoSavePolicy 实例；
与 MemoryAutoSavePolicy 字段同构的 dict；
None（等效于 "default"）

预设	保存内容
`"default"`	仅保存用户角色的文本事件（默认值）。`openviking` 后端因自身限制会同时包含助手角色
`"all"`	保存所有角色、所有事件类型的全部内容，包括思考内容和空文本
`"custom"`	以默认策略对象为起点，角色与事件类型不限制，但默认仍排除思考和空文本；显式字段可覆盖这些行为

使用预设字符串：

from veadk import Agent
from veadk.memory.long_term_memory import LongTermMemory

agent = Agent(
    name="ltm_agent",
    auto_save_session=True,
    auto_save_memory_policy="all",
    long_term_memory=LongTermMemory(backend="viking", app_name="ltm_demo"),
)

使用 MemoryAutoSavePolicy 实例进行精细控制：

from veadk import Agent
from veadk.memory import MemoryAutoSavePolicy
from veadk.memory.long_term_memory import LongTermMemory

agent = Agent(
    name="ltm_agent",
    auto_save_session=True,
    auto_save_memory_policy=MemoryAutoSavePolicy(
        preset="custom",
        include_roles=["user", "assistant"],
        include_event_types=["text", "function_call", "function_response"],
        include_thought=False,
    ),
    long_term_memory=LongTermMemory(backend="viking", app_name="ltm_demo"),
)

MemoryAutoSavePolicy 的完整字段：

字段	类型	默认值	说明
`preset`	`"default" \| "all" \| "custom"`	`"default"`	选择基础预设，未显式覆盖的字段沿用预设值
`include_roles`	`list["user" \| "assistant" \| "system"] \| None`	取决于预设	仅保存这些角色的事件。设为 `None` 表示不按角色过滤
`exclude_roles`	`list["user" \| "assistant" \| "system"]`	`[]`	排除这些角色的事件
`include_authors`	`list[str] \| None`	取决于预设	仅保存这些作者（`author`）的事件。设为 `None` 表示不按作者过滤
`exclude_authors`	`list[str]`	`[]`	排除这些作者的事件
`include_event_types`	`list[MemoryEventType] \| None`	取决于预设	仅保存这些事件类型。设为 `None` 表示不按事件类型过滤
`exclude_event_types`	`list[MemoryEventType]`	`[]`	排除这些事件类型
`text_only`	`bool`	取决于预设	为 `True` 且未显式指定 `include_event_types` 时，仅保留文本和思考类内容
`include_thought`	`bool`	取决于预设	是否保存思考（thought）内容
`include_empty_text`	`bool`	取决于预设	是否保存没有实际内容的空文本事件

MemoryEventType 包含以下事件类型：text、thought、function_call、function_response、tool_call、tool_response、media、executable_code、code_execution_result、transcription、error。

预设字符串提供快捷配置。传入 MemoryAutoSavePolicy 实例或 dict 时，以 preset 指定的基础预设为起点，仅显式设置的字段会覆盖预设值，其余字段保持预设的默认行为。

跨会话示例

先完成模型配置和本地记忆 embedding 配置，再运行端到端流程：会话 #1 告诉智能体一个事实并自动归档，然后在全新的会话 #2 提问，智能体通过检索长期记忆（而非上下文窗口）回忆起该事实。这里用 local 后端，需要 pip install "veadk-python[extensions]"。

import asyncio

from veadk import Agent, Runner
from veadk.memory.long_term_memory import LongTermMemory

APP_NAME = "ltm_demo"
USER_ID = "user-42"


def build_runner() -> Runner:
    ltm = LongTermMemory(backend="local", app_name=APP_NAME)
    agent = Agent(
        name="ltm_agent",
        instruction=(
            "你是个人助理。当用户问起之前告诉过你的事情时，"
            "使用 `load_memory` 工具去回忆。"
        ),
        long_term_memory=ltm,
        auto_save_session=True,
    )
    return Runner(agent=agent, app_name=APP_NAME, user_id=USER_ID)


async def main() -> None:
    runner = build_runner()

    print(
        "Session 1 ->",
        await runner.run(
            messages="记一下：我对花生过敏，而且我是素食者。",
            session_id="session-1",
        ),
    )

    print(
        "Session 2 ->",
        await runner.run(
            messages="帮我推荐一道适合我的菜，要考虑我的饮食限制。",
            session_id="session-2",
        ),
    )


if __name__ == "__main__":
    asyncio.run(main())

智能体能在会话 #2 中识别同一用户在会话 #1 留下的偏好，给出连贯、个性化的回答，如推荐一道无花生的素食菜品。

隔离和保存边界

长期记忆不等于永久保存：local 只在当前实例内存中保留数据，而且不按用户过滤检索。Mem0 不把 index 当作服务端隔离标识；OpenViking 需要明确 owner/context 和 peer 映射。应按后端说明确定应用与用户隔离，不能仅凭 LongTermMemory 构造参数推断自动保存的时间阈值不是后台定时任务，进程退出前也不保证触发最后一次保存；对必须保留的信息应主动调用保存并检索验证。search_memory() 返回空列表时也可能发生了后端错误。手动重复保存完整会话可能重复写入，自动保存的增量行为不适用于任意重复手动调用上文记忆管理代码为同一异步流程中的片段：先为 APP_NAME、USER_ID、SESSION_ID 赋值并确认查询得到非空 Session，再调用保存；完整入口见跨会话示例。启用 all 策略会将思考、工具输入输出和媒体信息发送到存储服务，执行前确认这些内容适合保留

概览

快速开始

核心组件

可观测

扩展

前端

安全

部署

统一入口：`LongTermMemory`

参数

选择后端

绑定到智能体

记忆管理

写入：`add_session_to_memory`

检索：`search_memory`

自动保存会话

控制保存内容：`auto_save_memory_policy`

跨会话示例

隔离和保存边界

​统一入口：LongTermMemory

​参数

​选择后端

​绑定到智能体

​记忆管理

​写入：add_session_to_memory

​检索：search_memory

​自动保存会话

​控制保存内容：auto_save_memory_policy

​跨会话示例

​隔离和保存边界

统一入口：`LongTermMemory`

参数

选择后端

绑定到智能体

记忆管理

写入：`add_session_to_memory`

检索：`search_memory`

自动保存会话

控制保存内容：`auto_save_memory_policy`

跨会话示例

隔离和保存边界