记忆与知识库

记忆和知识库都是可选能力。公开 quickstart 应在不配置 hosted 服务时也能运行；生产项目再按需接入长期记忆、知识库检索和框架工具。

能力边界

能力	用途	推荐范围
Session history	当前会话上下文	每个 session
长期记忆	用户偏好、轻量事实、历史决策	用户和应用
知识库	稳定文档、产品资料、政策说明	数据集或语料
框架工具	让 Agent 主动调用记忆或检索	Agent 实现
Ambient context	运行时在调用 runner 前补充上下文	KsADK 扩展

长期记忆不适合保存完整客户数据、token、图片二进制或长附件。

LangGraph 接入

prepare_state.py

def ksadk_prepare_state(payload: dict, session_context: dict) -> dict:
    return {
        "messages": payload.get("input_messages", []),
        "question": payload.get("input", ""),
        "knowledge": session_context.get("kb_context"),
        "memory": session_context.get("memory_context"),
    }

如果图只使用 messages，通常不需要 hook；当 graph state 有自定义字段时，再显式映射。

ADK 接入

ADK 项目优先使用 ADK 原生 tool 和 memory service。最小示例先只依赖模型调用；需要平台能力时再加入：

agent.py

from ksadk.knowledge_base.tool import search_knowledge
from ksadk.memory.tool import load_memory, save_memory

知识库工具

tools.py

from langchain_core.tools import tool

@tool
def search_knowledge_base(query: str) -> str:
    from ksadk.knowledge_base.tool import search_knowledge
    return search_knowledge(query)

知识库检索失败时要返回诊断，不要伪造成空结果。

记忆工具

tools.py

from langchain_core.tools import tool

@tool
def save_user_memory(content: str) -> str:
    from ksadk.memory.tool import save_memory
    return save_memory(content)

@tool
def load_user_memory(query: str) -> str:
    from ksadk.memory.tool import load_memory
    return load_memory(query)

推荐保存短事实，例如「发布说明先写结论，再写风险和验证方式」。

环境变量

常见变量：

KSADK_LTM_BACKEND
KSADK_LTM_NAMESPACE
KSADK_LTM_TOP_K
KSADK_KB_DATASET_ID
KSADK_KB_TOP_K

完整列表见环境变量。

OpenClaw memory backend(可选)

0.6.7 新增

OpenClaw runtime 支持通过 manifest 声明记忆 backend，新增进程内 LanceDB 记忆插件。

OpenClaw runtime 通过 MEMORY_BACKEND_MANIFEST 声明记忆 backend，backend_type 可选：

`backend_type`	说明	适用场景
`openclaw_default`	OpenClaw 内置默认记忆	不需要外部记忆服务时
`mem0`	接入外部 mem0 服务	已有 mem0 部署，需要跨会话/跨实例共享记忆
`lancedb`	进程内 LanceDB 记忆插件	无外部依赖的本地持久化记忆

几个要点：

lancedb 对应进程内 LanceDB 记忆插件（plugin id memory-lancedb），不走 agentengine openclaw deploy --memory-system CLI；该 CLI 的 Choice 仅 openclaw_default / mem0。
选择 mem0 时需提供 MEM0_API_KEY / MEM0_USER_ID / MEM0_BASE_URL（由托管平台注入）。
渲染产物 memory-lancedb 会 disable openclaw-mem0，避免重复加载。
manifest 的 config 可选覆盖 dbPath、embedding、storageOptions。

MEMORY_BACKEND_MANIFEST 示例（由托管平台注入）

backend_type: lancedb
config:
  dbPath: /data/agent-memory/lance
  embedding:
    provider: openai
    model: text-embedding-3-small
  storageOptions:
    topK: 5

公开口径

上述 manifest 与 secret 均由托管平台注入；公开文档不暴露内部 endpoint、account 或 token，示例值使用占位符（如 example.com / sk-test / cm-appkey-placeholder）。

完整变量列表见 ksadk 环境变量参考。