# https://github.com/memodb-io/memobase 项目说明书生成时间：2026-06-24 07:36:02 UTC ## 目录 - [Overview and Quickstart Guide](#page-1) - [Backend Architecture and API Layer](#page-2) - [Client SDKs and MCP Integration](#page-3) - [LLM Integration and Memory Processing Pipeline](#page-4) ## Overview and Quickstart Guide ### 相关页面相关主题：[Backend Architecture and API Layer](#page-2), [Client SDKs and MCP Integration](#page-3), [LLM Integration and Memory Processing Pipeline](#page-4)

相关源码文件

以下源码文件用于生成本页说明： - [readme.md](https://github.com/memodb-io/memobase/blob/main/readme.md) - [src/server/api/DEVELOPMENT.md](https://github.com/memodb-io/memobase/blob/main/src/server/api/DEVELOPMENT.md) - [src/client/memobase/core/blob.py](https://github.com/memodb-io/memobase/blob/main/src/client/memobase/core/blob.py) - [src/client/memobase/core/__init__.py](https://github.com/memodb-io/memobase/blob/main/src/client/memobase/core/__init__.py) - [src/mcp/README.md](https://github.com/memodb-io/memobase/blob/main/src/mcp/README.md) - [src/server/api/memobase_server/prompts/extract_profile.py](https://github.com/memodb-io/memobase/blob/main/src/server/api/memobase_server/prompts/extract_profile.py) - [src/server/api/memobase_server/prompts/merge_profile_yolo.py](https://github.com/memodb-io/memobase/blob/main/src/server/api/memobase_server/prompts/merge_profile_yolo.py) - [src/server/api/memobase_server/prompts/pick_related_profiles.py](https://github.com/memodb-io/memobase/blob/main/src/server/api/memobase_server/prompts/pick_related_profiles.py) - [src/server/api/memobase_server/prompts/profile_init_utils.py](https://github.com/memodb-io/memobase/blob/main/src/server/api/memobase_server/prompts/profile_init_utils.py) - [src/server/api/example_config/profile_for_assistant/config.yaml](https://github.com/memodb-io/memobase/blob/main/src/server/api/example_config/profile_for_assistant/config.yaml) - [src/server/api/example_config/profile_for_companion/config.yaml](https://github.com/memodb-io/memobase/blob/main/src/server/api/example_config/profile_for_companion/config.yaml) - [src/server/api/example_config/profile_for_education/config.yaml](https://github.com/memodb-io/memobase/blob/main/src/server/api/example_config/profile_for_education/config.yaml) - [src/server/api/memobase_server/controllers/modal/chat/utils.py](https://github.com/memodb-io/memobase/blob/main/src/server/api/memobase_server/controllers/modal/chat/utils.py) - [src/server/api/memobase_server/controllers/modal/chat/merge_yolo.py](https://github.com/memodb-io/memobase/blob/main/src/server/api/memobase_server/controllers/modal/chat/merge_yolo.py)

# Overview and Quickstart Guide ## 1. 项目定位与核心能力 Memobase 是一个面向 AI 应用的长期记忆管理系统，核心目标是把分散在多轮对话中的用户信息沉淀为可被 LLM 检索与注入的结构化"用户画像"（profile）。系统遵循"扁平优于嵌套""不为用户悄悄处理错误"等设计原则资料来源：[src/client/memobase/core/__init__.py:1-7]()。主要能力包含： - **结构化画像管理**：以 `TOPIC{tab}SUB_TOPIC{tab}MEMO` 的三段式记录用户事实和偏好，便于直接拼入 prompt 资料来源：[src/server/api/memobase_server/prompts/extract_profile.py:38-58]()。 - **多模态数据输入**：客户端 SDK 支持 `chat`、`doc`、`summary`、`code`、`image`、`transcript` 等多种 Blob 类型，可通过 `BlobData` 容器统一装载资料来源：[src/client/memobase/core/blob.py:1-65]()。 - **场景化画像模板**：内置助理（assistant）、伴侣（companion）、教育（education）等领域的样例 YAML 配置，可整体覆盖或追加资料来源：[src/server/api/example_config/profile_for_assistant/config.yaml:1-100]()。 - **MCP 协议集成**：提供符合 Anthropic MCP 规范的参考实现，便于接入 Claude 等兼容客户端资料来源：[src/mcp/README.md:1-12]()。 ## 2. 系统架构与数据流服务端基于 FastAPI 构建，采用 Controller / Connector 分层设计；外部依赖包括 PostgreSQL（持久化）、Redis（缓存）以及 OpenAI 等 LLM 服务资料来源：[src/server/api/DEVELOPMENT.md:1-50]()。客户端 SDK 提供 `u.context()` 等方法把画像格式化为可直接注入 prompt 的字符串资料来源：[readme.md:1-30]()。 ```mermaid sequenceDiagram participant Client as 客户端 SDK participant API as FastAPI 服务 participant Ctrl as Controller participant DB as PostgreSQL participant Cache as Redis participant LLM as LLM 服务 Client->>API: POST /api/v1/* 请求 API->>Ctrl: 路由分发 Ctrl->>Cache: 读取画像缓存 Ctrl->>DB: 查询/更新用户数据 Ctrl->>LLM: 抽取 / 合并画像 LLM-->>Ctrl: 结构化结果 Ctrl-->>API: 业务响应 API-->>Client: 返回 JSON ``` `controllers/modal/chat/` 子模块负责处理对话模态（modal），它在新数据进入时调用抽取 prompt，再通过 `merge_yolo` 批量合并到既有画像资料来源：[src/server/api/memobase_server/controllers/modal/chat/merge_yolo.py:1-60]()。 ## 3. 核心数据模型 `BlobData` 是 SDK 侧的通用载荷容器，其 `blob_type` 字段决定序列化方式，常见取值通过 `BlobType` 枚举进行约束资料来源：[src/client/memobase/core/blob.py:1-65]()。服务端使用 `UserProfileTopic` 表示一个画像主题，主题下挂载多个子主题（`sub_topics`），并可通过 `read_out_profile_config` 在 `overwrite_user_profiles` 或 `additional_user_profiles` 配置下整体覆盖或追加资料来源：[src/server/api/memobase_server/prompts/profile_init_utils.py:1-50]()。模板配置文件采用 YAML 格式。例如 `profile_for_companion` 关注 `interaction`、`personalization` 等主题，适用于情感陪伴场景资料来源：[src/server/api/example_config/profile_for_companion/config.yaml:1-30]()；`profile_for_education` 关注 `progress_tracking` 与 `engagement_metrics`，适合在线学习应用资料来源：[src/server/api/example_config/profile_for_education/config.yaml:1-50]()。 ## 4. 快速开始 ### 4.1 部署服务端参考 `DEVELOPMENT.md` 启动 FastAPI 应用，主路由前缀为 `/api/v1/*`，并提供 `/api/v1/healthcheck` 健康检查端点；建议在生产环境同时配置 PostgreSQL 与 Redis 连接资料来源：[src/server/api/DEVELOPMENT.md:1-50]()。 ### 4.2 启动 MCP 服务器 `src/mcp` 目录提供了开箱即用的 MCP 模板，暴露 `save_memory`、`get_user_profiles`、`search_memories` 三个工具；推荐使用 Docker 方式部署： ```bash docker build -t memobase-mcp --build-arg PORT=8050 . ``` 部署前需在 `.env` 中配置连接信息资料来源：[src/mcp/README.md:1-50]()。 ### 4.3 客户端调用示例在 Python 中使用 SDK 拉取用户画像上下文： ```python print(u.context(max_token_size=500, prefer_topics=["basic_info"])) ``` 返回的字符串可直接拼接到系统提示中，无需额外解析资料来源：[readme.md:1-30]()。 ## 5. 画像抽取与合并机制服务端使用 LLM 抽取对话中的事实，并通过"YOLO 合并"批量更新画像。`merge_profile_yolo` 提示词要求 LLM 输出 `UPDATE`、`APPEND`、`ABORT` 三种动作，且更新后的 memo 不得超过 5 句以保持简洁资料来源：[src/server/api/memobase_server/prompts/merge_profile_yolo.py:1-40]()。在注入上下文前，`pick_related_profiles` 会基于当前对话挑选最相关的画像条目，避免 prompt 膨胀资料来源：[src/server/api/memobase_server/prompts/pick_related_profiles.py:1-60]()。`pack_current_user_profiles` 负责把当前用户画像与项目配置对齐，决定是否启用 `strict_mode` 以及允许的主题范围资料来源：[src/server/api/memobase_server/controllers/modal/chat/utils.py:1-50]()。 ## See Also - [Profile Configuration Guide](#) - [MCP Integration Guide](#) - [API Reference](#) --- ## Backend Architecture and API Layer ### 相关页面相关主题：[Overview and Quickstart Guide](#page-1), [LLM Integration and Memory Processing Pipeline](#page-4), [Client SDKs and MCP Integration](#page-3)

相关源码文件

以下源码文件用于生成本页说明： - [src/server/api/DEVELOPMENT.md](https://github.com/memodb-io/memobase/blob/main/src/server/api/DEVELOPMENT.md) - [src/server/api/memobase_server/api_layer/roleplay.py](https://github.com/memodb-io/memobase/blob/main/src/server/api/memobase_server/api_layer/roleplay.py) - [src/server/api/memobase_server/api_layer/middleware.py](https://github.com/memodb-io/memobase/blob/main/src/server/api/memobase_server/api_layer/middleware.py) - [src/server/api/memobase_server/controllers/modal/chat/merge_yolo.py](https://github.com/memodb-io/memobase/blob/main/src/server/api/memobase_server/controllers/modal/chat/merge_yolo.py) - [src/server/api/memobase_server/prompts/extract_profile.py](https://github.com/memodb-io/memobase/blob/main/src/server/api/memobase_server/prompts/extract_profile.py) - [src/server/api/memobase_server/prompts/pick_related_profiles.py](https://github.com/memodb-io/memobase/blob/main/src/server/api/memobase_server/prompts/pick_related_profiles.py) - [src/server/api/memobase_server/prompts/zh_summary_entry_chats.py](https://github.com/memodb-io/memobase/blob/main/src/server/api/memobase_server/prompts/zh_summary_entry_chats.py) - [src/server/api/example_config/profile_for_assistant/config.yaml](https://github.com/memodb-io/memobase/blob/main/src/server/api/example_config/profile_for_assistant/config.yaml) - [src/server/api/example_config/profile_for_companion/config.yaml](https://github.com/memodb-io/memobase/blob/main/src/server/api/example_config/profile_for_companion/config.yaml) - [src/server/api/example_config/profile_for_education/config.yaml](https://github.com/memodb-io/memobase/blob/main/src/server/api/example_config/profile_for_education/config.yaml) - [src/client/memobase/core/blob.py](https://github.com/memodb-io/memobase/blob/main/src/client/memobase/core/blob.py) - [src/client/memobase-go/core/types.go](https://github.com/memodb-io/memobase/blob/main/src/client/memobase-go/core/types.go) - [src/mcp/README.md](https://github.com/memodb-io/memobase/blob/main/src/mcp/README.md) - [readme.md](https://github.com/memodb-io/memobase/blob/main/readme.md)

# 后端架构与 API 层 Memobase 是一个**基于用户档案（user profile）的长时记忆系统**，为 LLM 应用提供持久化的用户上下文与记忆能力。后端服务采用 FastAPI 框架实现，遵循清晰的"路由 → 控制器 → 模型"三层结构，并通过 PostgreSQL、Redis 与 LLM 服务协同工作。本页聚焦于后端的整体架构、API 层组织以及关键的数据流。 ## 整体系统架构后端服务的核心目标是为上层 LLM 应用提供低延迟（在线场景低于 100ms）的用户记忆读写能力，并通过"用户档案 + 事件时间线"两个核心数据结构保持对用户状态的持续追踪资料来源：[readme.md:14-25]()。后端的代码组织遵循如下分层结构资料来源：[src/server/api/DEVELOPMENT.md:3-19]()： ``` memobase_server/ ├── api_layer/ # FastAPI 路由与中间件 ├── models/ # SQLAlchemy 数据库模型、响应模型 ├── controllers/ # 业务逻辑（user/blob/buffer/profile/modal） ├── connectors/ # 外部服务（PostgreSQL、Redis）连接 ├── llms/ # LLM 服务初始化与 OpenAI 实现 └── prompts/ # LLM 提示词模板 ``` 下图展示了主要的组件关系与调用链路： ```mermaid graph TD A[FastAPI Server] --> B[API 路由层 api_layer] B --> C[鉴权中间件 middleware] B --> D[Controllers] D --> E[User Controller] D --> F[Blob Controller] D --> G[Buffer Controller] D --> H[Profile Controller] D --> I[Modal Controller] E & F & G & H & I --> J[connectors.py 数据库与缓存] E & F & G & H & I --> K[LLM 服务] K --> L[prompts 提示词模板] ``` 资料来源：[src/server/api/DEVELOPMENT.md:23-35]()。 ## API 层与中间件 API 入口由 FastAPI 应用统一对外暴露，路由前缀为 `/api/v1/*`，并通过 `global_wrapper_middleware` 全局中间件为每个请求注入请求 ID、项目 ID、版本号等上下文信息资料来源：[src/server/api/memobase_server/api_layer/middleware.py:39-66]()。中间件中的 `PATH_MAPPINGS` 显式列举了需要纳入项目状态校验的核心路径，包括用户档案、缓冲、事件、上下文等资料来源：[src/server/api/memobase_server/api_layer/middleware.py:24-34]()： | 路径前缀 | 含义 | | --- | --- | | `/api/v1/users/profile` | 用户档案读写 | | `/api/v1/users/buffer` | 缓冲刷写与控制 | | `/api/v1/users/event` | 事件时间线 | | `/api/v1/users/context` | 上下文组装 | | `/api/v1/users/blobs` | 数据块（Blob）管理 | | `/api/v1/blobs/insert` | 写入新的 Blob | API 层以"瘦路由"模式编写，业务参数与校验由 Pydantic 模型承担，例如角色扮演场景下的 `infer_proactive_topics` 路由允许调用方传入 `topk`、`max_token_size`、`prefer_topics`、`only_topics` 等精细化过滤参数资料来源：[src/server/api/memobase_server/api_layer/roleplay.py:9-44]()。 ## 控制器与数据流控制器层是后端的核心，负责串联数据库、缓存与 LLM 调用。一次典型的"用户写入 → 记忆更新"流程如下： 1. 客户端通过 `/api/v1/blobs/insert` 提交聊天或文档 Blob； 2. Buffer 控制器将 Blob 暂存到 PostgreSQL； 3. 当用户调用 `flush` 时，Buffer 控制器调用 Modal 控制器触发摘要与档案抽取； 4. Modal 控制器通过提示词模板（如 `extract_profile.py`、`merge_yolo.py`、`zh_summary_entry_chats.py`）调用 LLM； 5. 抽取出的事实与偏好写入用户档案；事件写入事件表资料来源：[src/server/api/DEVELOPMENT.md:37-54]()。对于"将多份相近记忆合并为单条"的 YOLO 合并场景，控制器会为每个待合并项构建 `(topic, sub_topic)` 键，并通过 `llm_complete` 以 `temperature=0.2` 的低温度调用 LLM，再由 `parse_string_into_merge_yolo_action` 解析回结构化的合并动作资料来源：[src/server/api/memobase_server/controllers/modal/chat/merge_yolo.py:30-58]()。上下文组装方向（即"读取侧"）由 `pick_related_profiles` 提示词驱动，LLM 扮演"专业记者"角色，根据当前对话上下文筛选出对回复最有帮助的若干条档案 ID 资料来源：[src/server/api/memobase_server/prompts/pick_related_profiles.py:55-78]()。 ## 配置、提示词与客户端 SDK 后端通过 YAML 配置文件定义"用户档案骨架"（topic/sub_topic 列表），并在系统启动时覆盖默认配置。仓库内置了三种典型场景模板： - **assistant（助手）**：聚焦任务优先级、自动化规则、通知偏好等资料来源：[src/server/api/example_config/profile_for_assistant/config.yaml:11-25]()； - **companion（陪伴型 AI）**：强调陪伴类型、交互风格、个性化标签资料来源：[src/server/api/example_config/profile_for_companion/config.yaml:18-40]()； - **education（教育）**：聚焦学科强弱项、学习风格、考试安排资料来源：[src/server/api/example_config/profile_for_education/config.yaml:7-27]()。提示词层是多语言且模块化的：`zh_summary_entry_chats.py` 提供了中文环境下"对话 → 摘要"的输入输出格式与时间归一化规则资料来源：[src/server/api/memobase_server/prompts/zh_summary_entry_chats.py:1-30]()；`extract_profile.py` 则给出英文环境下的档案抽取规范资料来源：[src/server/api/memobase_server/prompts/extract_profile.py:34-67]()。后端通过统一的 REST 接口对外暴露，官方同时维护了 Python 与 Go 两套 SDK。例如 Python 端的 `BlobData.to_blob()` 会根据 `blob_type` 选择具体的 `ChatBlob`、`SummaryBlob`、`DocBlob`、`ImageBlob` 等子类进行反序列化资料来源：[src/client/memobase/core/blob.py:38-58]()；Go 端则在 `core/types.go` 中定义了 `UserProfileData`、`EventData`、`ProfileDelta` 等数据结构资料来源：[src/client/memobase-go/core/types.go:9-44]()。此外，`src/mcp` 目录还提供了基于 Memobase 的 MCP（Model Context Protocol）服务器模板，实现 `save_memory`、`get_user_profiles`、`search_memories` 三类工具资料来源：[src/mcp/README.md:9-15]()。 ## 常见开发路径新增或修改后端能力时，推荐遵循以下顺序资料来源：[src/server/api/DEVELOPMENT.md:75-92]()： 1. 在 `api.py` 中定义路由； 2. 在 `controllers/` 下实现业务逻辑； 3. 在 `models/database.py` 中调整数据模型； 4. 在 `prompts/` 中迭代提示词； 5. 通过 `curl /api/v1/healthcheck` 与对应的业务接口进行联调。修改记忆处理流程时，优先调整提示词与 Profile/Buffer 控制器的协同逻辑；进行数据库变更时，需要同步更新模型、控制器与响应结构。 ## See Also - [User Profile Customization & Topics](https://docs.memobase.io/features/profile/profile) - [Memobase Playground](https://github.com/memodb-io/memobase-playground) - [Memobase Inspector](https://github.com/memodb-io/memobase-inspector) - 项目主页：[readme.md](https://github.com/memodb-io/memobase) --- ## Client SDKs and MCP Integration ### 相关页面相关主题：[Overview and Quickstart Guide](#page-1), [Backend Architecture and API Layer](#page-2)

相关源码文件

以下源码文件用于生成本页说明： - [src/client/memobase/core/entry.py](https://github.com/memodb-io/memobase/blob/main/src/client/memobase/core/entry.py) - [src/client/memobase/core/async_entry.py](https://github.com/memodb-io/memobase/blob/main/src/client/memobase/core/async_entry.py) - [src/client/memobase/core/blob.py](https://github.com/memodb-io/memobase/blob/main/src/client/memobase/core/blob.py) - [src/client/memobase-go/core/client.go](https://github.com/memodb-io/memobase/blob/main/src/client/memobase-go/core/client.go) - [src/client/memobase-go/core/user.go](https://github.com/memodb-io/memobase/blob/main/src/client/memobase-go/core/user.go) - [src/client/memobase-ts/src/client.ts](https://github.com/memodb-io/memobase/blob/main/src/client/memobase-ts/src/client.ts) - [src/mcp/README.md](https://github.com/memodb-io/memobase/blob/main/src/mcp/README.md) - [readme.md](https://github.com/memodb-io/memobase/blob/main/readme.md) - [src/server/readme.md](https://github.com/memodb-io/memobase/blob/main/src/server/readme.md)

# 客户端 SDK 与 MCP 集成 ## 概述 Memobase 是一套**基于用户画像的长期记忆系统**，后端基于 FastAPI + Postgres + Redis 构建并对外暴露 RESTful API（资料来源：[src/server/readme.md]()）。为了让不同技术栈的应用能够无缝接入，仓库同时提供了**多语言客户端 SDK**（Python / Go / TypeScript）以及一份面向 AI Agent 的 **MCP（Model Context Protocol）服务器参考实现**（资料来源：[readme.md]()、[src/mcp/README.md]()）。所有客户端最终都汇聚到同一套后端 API，因此不同语言的调用方拿到的画像（profile）与事件（event）语义完全一致。整体集成关系如下： ```mermaid graph LR App[LLM 应用 / Agent] --> Py[Python SDK] App --> Go[Go SDK] App --> Ts[TypeScript SDK] App --> Mcp[MCP Server] Py --> Api[Memobase REST API] Go --> Api Ts --> Api Mcp --> Api Api --> Db[(Postgres + Redis)] ``` ## 客户端 SDK 生态 ### Python SDK Python SDK 是项目最推荐的客户端，仓库根 README 中明确给出安装命令 `pip install memobase`（资料来源：[readme.md]()）。SDK 同时提供**同步**与**异步**两套入口：[src/client/memobase/core/entry.py]() 与 [src/client/memobase/core/async_entry.py]() 分别承载同步与异步调用路径，应用可按运行时上下文灵活选择。核心使用模式围绕 `User` 对象展开：传入 `project_url` 与 `project_token` 后即可创建用户、向缓冲区写入聊天（blob）、触发 flush，并通过 `u.context(max_token_size=..., prefer_topics=[...])` 生成可直接注入系统提示词的上下文片段（资料来源：[readme.md]()）。底层的 blob 数据结构由 [src/client/memobase/core/blob.py]() 抽象，用于承载待处理的聊天事件。 ### Go SDK Go 客户端位于 `src/client/memobase-go`，主要面向后端服务场景。[src/client/memobase-go/core/client.go]() 负责维护 `ProjectClient`（包含 `BaseURL` 与 `HTTPClient`），所有请求统一通过该客户端发出。 [src/client/memobase-go/core/user.go]() 实现了用户级别的典型操作：`GetAll(blobType, page, pageSize)` 用于分页获取指定类型的 blob ID，`Delete(blobID)` 删除单个 blob，`Flush(blobType, sync)` 则将缓冲区事件以同步或异步方式 flush。这些方法都遵循 `fmt.Sprintf("%s/...", u.ProjectClient.BaseURL, ...)` 的 URL 拼接规则，并通过 `network.UnpackResponse` 统一解析响应，与服务端路由结构对齐。 ### TypeScript SDK TypeScript 客户端位于 `src/client/memobase-ts`，主入口为 [src/client/memobase-ts/src/client.ts]()，面向 Web 端或 Node.js 应用。它与 Python/Go SDK 复用同一套 REST API，使前端也能直接管理用户、写入聊天与读取上下文。 ## MCP 集成层 ### 三大核心工具 `src/mcp/` 下的 MCP 服务器是一份**参考实现**，fork 自 `coleam00/mcp-mem0`（资料来源：[src/mcp/README.md]()）。它将 Memobase 的能力封装为三个 MCP 工具，供支持 MCP 协议的客户端（Cursor、Windsurf、Claude Desktop、n8n 等）直接调用： | 工具名称 | 功能描述 | | --- | --- | | `save_memory` | 将任意信息写入长期记忆，并建立语义索引 | | `get_user_profiles` | 拉取完整的用户画像 | | `search_memories` | 基于查询检索相关上下文 | ### 客户端连接配置 MCP 服务器同时支持 **stdio** 与 **SSE** 两种传输方式。以 SSE 为例，Cursor 的 `.cursor/mcp.json` 配置为（资料来源：[src/mcp/README.md]()）： ```json { "mcpServers": { "memobase": { "transport": "sse", "url": "http://localhost:8050/sse" } } } ``` 需注意，Windsurf 使用 `serverUrl` 而非 `url`；n8n 运行在容器内时，应将 `localhost` 替换为 `host.docker.internal` 才能访问宿主机的 MCP 服务（资料来源：[src/mcp/README.md]()）。 ## 配置、部署与使用模式部署 MCP 服务有两条路径：**本地开发**通过 `uv pip install -e .` 安装依赖后，复制 `.env.example` 为 `.env` 并填入 `MEMOBASE_URL` 与 `MEMOBASE_TOKEN`；**容器化部署**则执行 `docker build -t memobase-mcp --build-arg PORT=8050 .` 构建镜像，再通过 `docker run -p 8050:8050 memobase-mcp` 启动（资料来源：[src/mcp/README.md]()）。后端服务在 `src/server` 下通过 `docker-compose build && docker-compose up` 启动（资料来源：[src/server/readme.md]()）。无论是 SDK 还是 MCP，调用方只需拿到两项信息即可联通：`project_url`（本地 `http://localhost:8019`，云端 `https://api.memobase.dev`）与 `project_token`（本地 `secret`，云端 `sk-proj-xxxxxx`），资料来源：[readme.md]()、[src/server/readme.md]()。 ## 参见 - [Server API 与控制器架构（DEVELOPMENT.md）](https://github.com/memodb-io/memobase/blob/main/src/server/api/DEVELOPMENT.md) - [配置文件示例（example_config/）](https://github.com/memodb-io/memobase/tree/main/src/server/api/example_config) - [提示词模板（prompts/）](https://github.com/memodb-io/memobase/tree/main/src/server/api/memobase_server/prompts) --- ## LLM Integration and Memory Processing Pipeline ### 相关页面相关主题：[Backend Architecture and API Layer](#page-2), [Overview and Quickstart Guide](#page-1)

相关源码文件

以下源码文件用于生成本页说明： - [src/server/api/DEVELOPMENT.md](https://github.com/memodb-io/memobase/blob/main/src/server/api/DEVELOPMENT.md) - [src/server/api/readme.md](https://github.com/memodb-io/memobase/blob/main/src/server/api/readme.md) - [readme.md](https://github.com/memodb-io/memobase/blob/main/readme.md) - [src/server/api/memobase_server/controllers/modal/chat/extract.py](https://github.com/memodb-io/memobase/blob/main/src/server/api/memobase_server/controllers/modal/chat/extract.py) - [src/server/api/memobase_server/controllers/modal/chat/merge.py](https://github.com/memodb-io/memobase/blob/main/src/server/api/memobase_server/controllers/modal/chat/merge.py) - [src/server/api/memobase_server/controllers/modal/chat/merge_yolo.py](https://github.com/memodb-io/memobase/blob/main/src/server/api/memobase_server/controllers/modal/chat/merge_yolo.py) - [src/server/api/memobase_server/controllers/modal/chat/event_summary.py](https://github.com/memodb-io/memobase/blob/main/src/server/api/memobase_server/controllers/modal/chat/event_summary.py) - [src/server/api/memobase_server/controllers/buffer.py](https://github.com/memodb-io/memobase/blob/main/src/server/api/memobase_server/controllers/buffer.py) - [src/server/api/memobase_server/prompts/extract_profile.py](https://github.com/memodb-io/memobase/blob/main/src/server/api/memobase_server/prompts/extract_profile.py) - [src/server/api/memobase_server/prompts/organize_profile.py](https://github.com/memodb-io/memobase/blob/main/src/server/api/memobase_server/prompts/organize_profile.py) - [src/server/api/memobase_server/prompts/merge_profile_yolo.py](https://github.com/memodb-io/memobase/blob/main/src/server/api/memobase_server/prompts/merge_profile_yolo.py) - [src/server/api/memobase_server/prompts/pick_related_profiles.py](https://github.com/memodb-io/memobase/blob/main/src/server/api/memobase_server/prompts/pick_related_profiles.py) - [src/server/api/example_config/only_strict_profile/config.yaml](https://github.com/memodb-io/memobase/blob/main/src/server/api/example_config/only_strict_profile/config.yaml) - [src/server/api/example_config/profile_for_education/config.yaml](https://github.com/memodb-io/memobase/blob/main/src/server/api/example_config/profile_for_education/config.yaml) - [src/server/api/example_config/profile_for_companion/config.yaml](https://github.com/memodb-io/memobase/blob/main/src/server/api/example_config/profile_for_companion/config.yaml) - [src/mcp/README.md](https://github.com/memodb-io/memobase/blob/main/src/mcp/README.md)

# LLM Integration and Memory Processing Pipeline ## 概述与设计目标 Memobase 是一个面向 LLM 应用的用户记忆系统，其核心能力是将非结构化的对话、文档、图片等内容，通过大语言模型转化为可检索、可拼接的结构化用户画像与事件时间线资料来源：[readme.md](https://github.com/memodb-io/memobase/blob/main/readme.md)。整个系统的服务端基于 FastAPI + PostgreSQL + Redis 构建，而真正驱动记忆演化的是 LLM Integration 与 Memory Processing Pipeline 这两层能力资料来源：[src/server/api/DEVELOPMENT.md](https://github.com/memodb-io/memobase/blob/main/src/server/api/DEVELOPMENT.md)。与同类记忆方案不同，Memobase 强调三项关键指标：性能、LLM 成本与在线延迟。从 `0.0.40` 版本开始，单次记忆处理流程将 LLM 调用次数由约 3–10 次压缩为固定的 3 次，整体 token 成本下降约 40–50% 资料来源：[readme.md](https://github.com/memodb-io/memobase/blob/main/readme.md)。这得益于对 Pipeline 中各阶段 Prompt 的精炼以及对 YOLO 合并模式的引入。 ## 整体架构 LLM Integration 层位于 `memobase_server/llms/` 之下，向上对接各 Modal 控制器，向下对接 OpenAI 兼容的推理服务资料来源：[src/server/api/readme.md](https://github.com/memodb-io/memobase/blob/main/src/server/api/readme.md)。Memory Processing Pipeline 则由若干 Modal 控制器串联而成，主要包含三个阶段： ```mermaid flowchart LR A[Buffer Zone
缓冲数据] --> B[Extract
事实抽取] B --> C[Merge / Merge-YOLO
记忆合并] C --> D[Organize
画像整理] D --> E[(UserProfile + EventTimeline
PostgreSQL + Redis)] F[Event Summary
事件摘要] --> E G[Event Tagging
事件打标] --> E ``` Pipeline 的入口是用户级 Buffer（缓冲区），它把高并发的会话消息按用户聚合为批处理任务，再触发后续的抽取与合并流程资料来源：[src/server/api/DEVELOPMENT.md](https://github.com/memodb-io/memobase/blob/main/src/server/api/DEVELOPMENT.md)。 ## 核心阶段详解 ### 1. 缓冲与批处理（Buffer）每个用户在 Memobase 中都拥有一个缓冲区，用来把零散的 chat / blob 消息攒批处理，从而把 LLM 开销摊薄资料来源：[readme.md](https://github.com/memodb-io/memobase/blob/main/readme.md)。`controllers/buffer.py` 与 `controllers/buffer_background.py` 负责管理缓冲生命周期、调度后台 worker，保证即使在请求高峰期也不会阻塞主链路。 ### 2. 事实抽取（Extract）抽取阶段调用 LLM 从原始数据中提取出事实与偏好，输出为 `TOPIC{tab}SUB_TOPIC{tab}MEMO` 形式的列表资料来源：[src/server/api/memobase_server/prompts/extract_profile.py](https://github.com/memodb-io/memobase/blob/main/src/server/api/memobase_server/prompts/extract_profile.py)。该 Prompt 同时内置了 Topic/Sub-topic 的白名单与示例 few-shot，确保抽取结果与配置文件中定义的画像结构对齐。可在 `example_config/profile_for_education/config.yaml` 与 `profile_for_companion/config.yaml` 中按业务定制抽取主题，例如教育场景关注 `academic_profile.weak_subjects`，陪伴场景关注 `companion_preferences.interaction_style` 资料来源：[src/server/api/example_config/profile_for_education/config.yaml](https://github.com/memodb-io/memobase/blob/main/src/server/api/example_config/profile_for_education/config.yaml)、[src/server/api/example_config/profile_for_companion/config.yaml](https://github.com/memodb-io/memobase/blob/main/src/server/api/example_config/profile_for_companion/config.yaml)。 ### 3. 记忆合并（Merge / Merge-YOLO）合并阶段负责将新事实与历史画像进行冲突解决与去重。`merge_yolo.py` 实现了一次 LLM 调用内对多个新备忘做整体合并，避免了逐条合并带来的 token 浪费资料来源：[src/server/api/memobase_server/controllers/modal/chat/merge_yolo.py](https://github.com/memodb-io/memobase/blob/main/src/server/api/memobase_server/controllers/modal/chat/merge_yolo.py)。Prompt 模板定义了 `UPDATE / APPEND / ABORT` 三种动作，要求最终记忆长度不超过 5 句，并保留时间戳注释资料来源：[src/server/api/memobase_server/prompts/merge_profile_yolo.py](https://github.com/memodb-io/memobase/blob/main/src/server/api/memobase_server/prompts/merge_profile_yolo.py)。 ### 4. 画像整理与检索（Organize / Pick Related） `organize_profile.py` 控制每个 Topic 下 Sub-topic 的数量上限，并允许丢弃与主题无关的条目资料来源：[src/server/api/memobase_server/prompts/organize_profile.py](https://github.com/memodb-io/memobase/blob/main/src/server/api/memobase_server/prompts/organize_profile.py)。在上下文拼接阶段，`pick_related_profiles.py` 让 LLM 以记者身份从当前对话反推需要哪些记忆片段作为补充，从而在 `/context` 接口上实现 < 100ms 的检索延迟资料来源：[src/server/api/memobase_server/prompts/pick_related_profiles.py](https://github.com/memodb-io/memobase/blob/main/src/server/api/memobase_server/prompts/pick_related_profiles.py)、[readme.md](https://github.com/memodb-io/memobase/blob/main/readme.md)。 ### 5. 事件摘要与打标（Event Summary & Tagging） `event_summary.py` 调用 LLM 对事件做摘要并打标签，写入时间线以支持 `0.0.37` 引入的细粒度事件检索资料来源：[src/server/api/memobase_server/controllers/modal/chat/event_summary.py](https://github.com/memodb-io/memobase/blob/main/src/server/api/memobase_server/controllers/modal/chat/event_summary.py)、[readme.md](https://github.com/memodb-io/memobase/blob/main/readme.md)。 ## 配置与可调参数下表列出与 Pipeline 行为最相关的几项配置项，均可在 `config.yaml` 中按需开启： | 配置项 | 作用 | 默认行为 | 来源 | | --- | --- | --- | --- | | `best_llm_model` | 指定用于精确抽取/合并的强模型 | 通常为 `gpt-4o` | [example_config/only_strict_profile/config.yaml](https://github.com/memodb-io/memobase/blob/main/src/server/api/example_config/only_strict_profile/config.yaml) | | `enable_event_embedding` | 是否为事件生成向量 | 默认开启 | [example_config/only_strict_profile/config.yaml](https://github.com/memodb-io/memobase/blob/main/src/server/api/example_config/only_strict_profile/config.yaml) | | `enable_event_summary` | 是否生成事件摘要 | 默认开启 | [example_config/only_strict_profile/config.yaml](https://github.com/memodb-io/memobase/blob/main/src/server/api/example_config/only_strict_profile/config.yaml) | | `profile_strict_mode` | 严格模式：只保留命中白名单的画像 | 关闭 | [example_config/only_strict_profile/config.yaml](https://github.com/memodb-io/memobase/blob/main/src/server/api/example_config/only_strict_profile/config.yaml) | | `overwrite_user_profiles` | 完全自定义 Topic/Sub-topic 结构 | 提供若干内置模板 | [example_config/profile_for_companion/config.yaml](https://github.com/memodb-io/memobase/blob/main/src/server/api/example_config/profile_for_companion/config.yaml) | 通过组合以上开关与模板，开发者既可以让 Memobase 扮演轻量级 RAG 记忆层（关闭 summary/strict），也可以让其承担完整的“用户画像 + 事件时间线”双轨记忆系统。 ## 常见失败模式 - **LLM 返回格式异常**：`extract_profile` 与 `merge_profile_yolo` 都依赖结构化输出，若模型未按 `TOPIC{tab}SUB_TOPIC{tab}MEMO` 或 `UPDATE/APPEND/ABORT` 返回，Pipeline 会在 `r.ok()` 校验处失败并记录 `TRACE_LOG` 资料来源：[src/server/api/memobase_server/controllers/modal/chat/merge_yolo.py](https://github.com/memodb-io/memobase/blob/main/src/server/api/memobase_server/controllers/modal/chat/merge_yolo.py)。 - **事件标签不在白名单**：`event_summary.tag_event` 会丢弃未匹配 `available_event_tags` 的标签，避免脏数据入库资料来源：[src/server/api/memobase_server/controllers/modal/chat/event_summary.py](https://github.com/memodb-io/memobase/blob/main/src/server/api/memobase_server/controllers/modal/chat/event_summary.py)。 - **无对应合并动作**：YOLO 模式下若 LLM 未为某条新备忘返回动作，会跳过该条并写日志，不会中断整体流程资料来源：[src/server/api/memobase_server/controllers/modal/chat/merge_yolo.py](https://github.com/memodb-io/memobase/blob/main/src/server/api/memobase_server/controllers/modal/chat/merge_yolo.py)。 ## See Also - [Server Architecture Overview](./Architecture.md) — FastAPI/Postgres/Redis 总览 - [Configuration Guide](./Configuration.md) — `config.yaml` 完整字段说明 - [MCP Server Integration](./MCP-Server.md) — 通过 Model Context Protocol 把 Memobase 暴露给 Agent 资料来源：[src/mcp/README.md](https://github.com/memodb-io/memobase/blob/main/src/mcp/README.md) --- --- ## Doramagic 踩坑日志项目：memodb-io/memobase 摘要：发现 12 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安装坑 - 来源证据：“add_user” and “update_user” handle additional data differently。 ## 1. 安装坑 · 来源证据：“add_user” and “update_user” handle additional data differently - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：“add_user” and “update_user” handle additional data differently - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/memodb-io/memobase/issues/155 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 2. 安装坑 · 来源证据：Your AI needs an identity — here's how to fix that - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Your AI needs an identity — here's how to fix that - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/memodb-io/memobase/issues/158 | 来源类型 github_issue 暴露的待验证使用条件。 ## 3. 安装坑 · 来源证据：memobase embedding模型维度不匹配 - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：memobase embedding模型维度不匹配 - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/memodb-io/memobase/issues/76 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。 ## 4. 配置坑 · 来源证据：[Question] : user_event_gist 在执行插入是否有重复事件去重操作 - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[Question] : user_event_gist 在执行插入是否有重复事件去重操作 - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/memodb-io/memobase/issues/159 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 5. 能力坑 · 能力判断依赖假设 - 严重度：medium - 证据强度：source_linked - 发现：README/documentation is current enough for a first validation pass. - 对用户的影响：假设不成立时，用户拿不到承诺的能力。 - 证据：capability.assumptions | https://github.com/memodb-io/memobase | README/documentation is current enough for a first validation pass. ## 6. 运行坑 · 来源证据：search_event returns KeyError 'events' - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：search_event returns KeyError 'events' - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/memodb-io/memobase/issues/137 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 7. 维护坑 · 维护活跃度未知 - 严重度：medium - 证据强度：source_linked - 发现：未记录 last_activity_observed。 - 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 - 证据：evidence.maintainer_signals | https://github.com/memodb-io/memobase | last_activity_observed missing - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 证据：downstream_validation.risk_items | https://github.com/memodb-io/memobase | no_demo; severity=medium ## 9. 安全/权限坑 · 存在评分风险 - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 对用户的影响：风险会影响是否适合普通用户安装。 - 证据：risks.scoring_risks | https://github.com/memodb-io/memobase | no_demo; severity=medium ## 10. 安全/权限坑 · 来源证据：Error in get_embedding: Failed to embed texts: 404 page not found Traceback (most recent call last) - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Error in get_embedding: Failed to embed texts: 404 page not found Traceback (most recent call last) - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 证据：community_evidence:github | https://github.com/memodb-io/memobase/issues/153 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 11. 维护坑 · issue/PR 响应质量未知 - 严重度：low - 证据强度：source_linked - 发现：issue_or_pr_quality=unknown。 - 对用户的影响：用户无法判断遇到问题后是否有人维护。 - 证据：evidence.maintainer_signals | https://github.com/memodb-io/memobase | issue_or_pr_quality=unknown ## 12. 维护坑 · 发布节奏不明确 - 严重度：low - 证据强度：source_linked - 发现：release_recency=unknown。 - 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。 - 证据：evidence.maintainer_signals | https://github.com/memodb-io/memobase | release_recency=unknown