第 4 章 MemoryService 初始化与配置

MemoryService 是 memU 自托管版的组合根（Composition Root）：配置在这里一次性注入，后续只调 memorize() / retrieve()。本章讲清每个配置块的作用与推荐组合。

4.1 最小初始化

from memu import MemoryService

service = MemoryService(
    llm_profiles={
        "default": {
            "api_key": "your_api_key",
            "chat_model": "gpt-4o-mini",
        },
    },
    database_config={
        "metadata_store": {"provider": "inmemory"},
    },
)
​

三个配置块几乎总是需要关心：

4.2 llm_profiles 详解

memU 用 Profile 机制把不同任务路由到不同模型或 Provider。

内置 Profile 名

default Profile 常用字段

llm_profiles={
    "default": {
        "api_key": "sk-...",
        "base_url": "https://api.openai.com/v1",  # 兼容端点
        "chat_model": "gpt-4o-mini",
        "client_backend": "sdk",   # sdk | httpx
        "provider": "openai",      # openai | openrouter | doubao | grok
    },
    "embedding": {
        "api_key": "sk-...",
        "embed_model": "text-embedding-3-small",
    },
}
​

国内模型示例（通义千问）

service = MemoryService(
    llm_profiles={
        "default": {
            "base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1",
            "api_key": "your_dashscope_key",
            "chat_model": "qwen-max",
            "client_backend": "sdk",
        },
        "embedding": {
            "base_url": "https://api.voyageai.com/v1",
            "api_key": "your_voyage_key",
            "embed_model": "voyage-3.5-lite",
        },
    },
)
​

Chat 与 Embedding 可以使用不同 Provider——这是生产环境常见做法。

4.3 database_config 详解

database_config={
    "metadata_store": {
        "provider": "inmemory",  # inmemory | sqlite | postgres
    },
}
​

Postgres 配置示例见第 8 章。

4.4 retrieve_config 详解

在服务初始化时设定，影响所有后续 retrieve() 调用：

# RAG 模式：向量优先，低延迟
service_rag = MemoryService(
    llm_profiles={...},
    database_config={...},
    retrieve_config={
        "method": "rag",
        # 可选微调：
        # "route_intention": True,
        # "sufficiency_check": True,
    },
)

# LLM 模式：语义排序，更深
service_llm = MemoryService(
    llm_profiles={...},
    database_config={...},
    retrieve_config={"method": "llm"},
)
​

重要：两种模式可以共用同一存储——初始化两个 Service 实例，共享底层 store 即可（进阶用法见第 6 章）。

4.5 memorize_config 与 UserConfig

memorize_config

控制写入流水线行为（可选）：

service = MemoryService(
    llm_profiles={...},
    memorize_config={
        # 各步骤可选用不同 llm_profile
        # 高级场景可在 Pipeline 层替换步骤（第 10 章）
    },
)
​

入门阶段保持默认即可。

UserConfig（作用域模型）

定义哪些字段参与多租户隔离：

from memu import MemoryService

service = MemoryService(
    llm_profiles={...},
    user_config={
        "model": {
            "user_id": str,
            "agent_id": str,
            "session_id": str,
        },
    },
)
​

配置后，user={"user_id": "x"} 与 where={"user_id": "x"} 会在 Resource / Item / Category / Relation 各表生效。

4.6 memory_files_config（Markdown 导出）

控制是否将结构化记忆导出为 Markdown 树（第 10 章）：

service = MemoryService(
    llm_profiles={...},
    memory_files_config={
        "enabled": False,       # 默认关闭
        "output_dir": "./memory_export",
        "synthesize": False,  # True 时用 LLM 合成 MEMORY 正文
    },
)
​

4.7 MemUService vs MemoryService

官方 SDK 中存在两个入口类名（随版本演进）：

初始化参数结构相同。以你安装版本的官方 README 为准；本教程统一使用 MemoryService。

4.8 生命周期与并发

import asyncio
from memu import MemoryService

async def app_lifespan():
    service = MemoryService(...)

    # 应用运行期间复用同一实例
    await service.memorize(...)
    await service.retrieve(...)

    # 可选：导出记忆树
    # await service.export_memory_files(user={"user_id": "u1"})

asyncio.run(app_lifespan())
​

最佳实践：

• 进程级单例：一个 MemoryService 服务多个请求
• memorize() 与 retrieve() 均为 async，需在 async 上下文调用
• Postgres 后端注意连接池与迁移初始化（第 8 章）

4.9 配置组合推荐

开发环境

MemoryService(
    llm_profiles={"default": {"api_key": "...", "chat_model": "gpt-4o-mini"}},
    database_config={"metadata_store": {"provider": "inmemory"}},
    retrieve_config={"method": "rag"},
)
​

生产环境

MemoryService(
    llm_profiles={
        "default": {"api_key": "...", "chat_model": "gpt-4o"},
        "embedding": {"api_key": "...", "embed_model": "text-embedding-3-small"},
    },
    database_config={"metadata_store": {"provider": "postgres", "dsn": "..."}},
    retrieve_config={"method": "rag", "sufficiency_check": True},
    user_config={"model": {"user_id": str, "agent_id": str}},
)
​

高精度场景

• 检索改用 method="llm"
• Chat 模型升级至 GPT-4o / Claude 3.5
• 开启 sufficiency_check 减少无关召回

4.10 本章小结

• MemoryService 集中管理 LLM、存储、检索、作用域、导出五类配置。
• llm_profiles 支持多 Provider；embedding 建议独立 Profile。
• retrieve_config.method 在初始化时设定，决定 RAG 或 LLM 流水线。
• 作用域通过 user / where 一致传递。

动手实验

1. 分别用 inmemory 与 sqlite 初始化，感受持久化差异（重启进程后数据是否还在）。
2. 配置双 Profile：chat 用国产模型，embedding 用 OpenAI，跑通 memorize + retrieve。
3. 故意漏配 embedding Profile，观察 RAG 模式是否报错或回退。

下一章：第 5 章 — memorize 写入流水线原理与实战。

参见：第 3 章返回结构；第 8 章 Postgres 配置。