长期记忆

长期记忆跨会话、跨时间保存重要信息，包括用户偏好、任务历史、知识要点或长期状态。短期记忆只在单次会话内有效，而长期记忆让智能体在不同会话之间也能记住事实。为什么需要它：

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

统一入口：`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`	`""`	存储记忆所用的索引/集合名。为空时回退到 `app_name`，再为空则用 `default_app`。
`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 指定的基础预设为起点，仅显式设置的字段会覆盖预设值，其余字段保持预设的默认行为。

跨会话示例

下面是端到端流程：会话 #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 留下的偏好，给出连贯、个性化的回答，如推荐一道无花生的素食菜品。

概览

快速开始

核心组件

可观测

扩展

前端

安全

部署

统一入口：`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`

跨会话示例