memobase 项目说明书

Doramagic 项目包 · 项目说明书

memobase 项目

基于用户画像的长期记忆，专为 AI 聊天机器人应用打造。

Overview and Quickstart Guide

Memobase 是一个面向 AI 应用的长期记忆管理系统，核心目标是把分散在多轮对话中的用户信息沉淀为可被 LLM 检索与注入的结构化"用户画像"（profile）。系统遵循"扁平优于嵌套""不为用户悄悄处理错误"等设计原则资料来源：[src/client/memobase/core/init.py:1-7]()。

章节 相关页面

继续阅读本节完整说明和来源证据。

章节 4.1 部署服务端

继续阅读本节完整说明和来源证据。

章节 4.2 启动 MCP 服务器

继续阅读本节完整说明和来源证据。

章节 4.3 客户端调用示例

继续阅读本节完整说明和来源证据。

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。

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 方式部署：

docker build -t memobase-mcp --build-arg PORT=8050 .

部署前需在 .env 中配置连接信息资料来源：src/mcp/README.md:1-50。

4.3 客户端调用示例

在 Python 中使用 SDK 拉取用户画像上下文：

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。

Backend Architecture and API Layer

Memobase 是一个基于用户档案（user profile）的长时记忆系统，为 LLM 应用提供持久化的用户上下文与记忆能力。后端服务采用 FastAPI 框架实现，遵循清晰的"路由 → 控制器 → 模型"三层结构，并通过 PostgreSQL、Redis 与 LLM 服务协同工作。本页聚焦于后端的整体架构、API 层组织以及关键的数据流。

章节 相关页面

继续阅读本节完整说明和来源证据。

后端架构与 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 提示词模板

下图展示了主要的组件关系与调用链路：

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 调用。一次典型的"用户写入 → 记忆更新"流程如下：

客户端通过 /api/v1/blobs/insert 提交聊天或文档 Blob；
Buffer 控制器将 Blob 暂存到 PostgreSQL；
当用户调用 flush 时，Buffer 控制器调用 Modal 控制器触发摘要与档案抽取；
Modal 控制器通过提示词模板（如 extract_profile.py、merge_yolo.py、zh_summary_entry_chats.py）调用 LLM；
抽取出的事实与偏好写入用户档案；事件写入事件表资料来源：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：

在 api.py 中定义路由；
在 controllers/ 下实现业务逻辑；
在 models/database.py 中调整数据模型；
在 prompts/ 中迭代提示词；
通过 curl /api/v1/healthcheck 与对应的业务接口进行联调。

修改记忆处理流程时，优先调整提示词与 Profile/Buffer 控制器的协同逻辑；进行数据库变更时，需要同步更新模型、控制器与响应结构。

Client SDKs and MCP Integration

Memobase 是一套基于用户画像的长期记忆系统，后端基于 FastAPI + Postgres + Redis 构建并对外暴露 RESTful API（资料来源：[src/server/readme.md]()）。为了让不同技术栈的应用能够无缝接入，仓库同时提供了多语言客户端 SDK（Python / Go / TypeScript）以及一份面向 AI Agent 的 ...

章节 相关页面

继续阅读本节完整说明和来源证据。

章节 Python SDK

继续阅读本节完整说明和来源证据。

章节 Go SDK

继续阅读本节完整说明和来源证据。

章节 TypeScript SDK

继续阅读本节完整说明和来源证据。

客户端 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）语义完全一致。整体集成关系如下：

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）：

{
  "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。

参见

来源：https://github.com/memodb-io/memobase / 项目说明书

LLM Integration and Memory Processing Pipeline

Memobase 是一个面向 LLM 应用的用户记忆系统，其核心能力是将非结构化的对话、文档、图片等内容，通过大语言模型转化为可检索、可拼接的结构化用户画像与事件时间线资料来源：readme.md。整个系统的服务端基于 FastAPI + PostgreSQL + Redis 构建，而真正驱动记忆演化的是 LLM Integration 与 Memory Processi...

章节 相关页面

继续阅读本节完整说明和来源证据。

章节 1. 缓冲与批处理（Buffer）

继续阅读本节完整说明和来源证据。

章节 2. 事实抽取（Extract）

继续阅读本节完整说明和来源证据。

章节 3. 记忆合并（Merge / Merge-YOLO）

继续阅读本节完整说明和来源证据。

概述与设计目标

与同类记忆方案不同，Memobase 强调三项关键指标：性能、LLM 成本与在线延迟。从 0.0.40 版本开始，单次记忆处理流程将 LLM 调用次数由约 3–10 次压缩为固定的 3 次，整体 token 成本下降约 40–50% 资料来源：readme.md。这得益于对 Pipeline 中各阶段 Prompt 的精炼以及对 YOLO 合并模式的引入。

整体架构

LLM Integration 层位于 memobase_server/llms/ 之下，向上对接各 Modal 控制器，向下对接 OpenAI 兼容的推理服务资料来源：src/server/api/readme.md。Memory Processing Pipeline 则由若干 Modal 控制器串联而成，主要包含三个阶段：

flowchart LR
    A[Buffer Zone<br/>缓冲数据] --> B[Extract<br/>事实抽取]
    B --> C[Merge / Merge-YOLO<br/>记忆合并]
    C --> D[Organize<br/>画像整理]
    D --> E[(UserProfile + EventTimeline<br/>PostgreSQL + Redis)]
    F[Event Summary<br/>事件摘要] --> E
    G[Event Tagging<br/>事件打标] --> E

Pipeline 的入口是用户级 Buffer（缓冲区），它把高并发的会话消息按用户聚合为批处理任务，再触发后续的抽取与合并流程资料来源：src/server/api/DEVELOPMENT.md。

核心阶段详解

1. 缓冲与批处理（Buffer）

每个用户在 Memobase 中都拥有一个缓冲区，用来把零散的 chat / blob 消息攒批处理，从而把 LLM 开销摊薄资料来源：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。该 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、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。Prompt 模板定义了 UPDATE / APPEND / ABORT 三种动作，要求最终记忆长度不超过 5 句，并保留时间戳注释资料来源：src/server/api/memobase_server/prompts/merge_profile_yolo.py。

organize_profile.py 控制每个 Topic 下 Sub-topic 的数量上限，并允许丢弃与主题无关的条目资料来源：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、readme.md。

5. 事件摘要与打标（Event Summary & Tagging）

event_summary.py 调用 LLM 对事件做摘要并打标签，写入时间线以支持 0.0.37 引入的细粒度事件检索资料来源：src/server/api/memobase_server/controllers/modal/chat/event_summary.py、readme.md。

配置与可调参数

下表列出与 Pipeline 行为最相关的几项配置项，均可在 config.yaml 中按需开启：

配置项	作用	默认行为	来源
`best_llm_model`	指定用于精确抽取/合并的强模型	通常为 `gpt-4o`	example_config/only_strict_profile/config.yaml
`enable_event_embedding`	是否为事件生成向量	默认开启	example_config/only_strict_profile/config.yaml
`enable_event_summary`	是否生成事件摘要	默认开启	example_config/only_strict_profile/config.yaml
`profile_strict_mode`	严格模式：只保留命中白名单的画像	关闭	example_config/only_strict_profile/config.yaml
`overwrite_user_profiles`	完全自定义 Topic/Sub-topic 结构	提供若干内置模板	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。
事件标签不在白名单：event_summary.tag_event 会丢弃未匹配 available_event_tags 的标签，避免脏数据入库资料来源：src/server/api/memobase_server/controllers/modal/chat/event_summary.py。
无对应合并动作：YOLO 模式下若 LLM 未为某条新备忘返回动作，会跳过该条并写日志，不会中断整体流程资料来源：src/server/api/memobase_server/controllers/modal/chat/merge_yolo.py。

失败模式与踩坑日记

保留 Doramagic 在发现、验证和编译中沉淀的项目专属风险，不把社区讨论只当作装饰信息。

high 来源证据：“add_user” and “update_user” handle additional data differently

可能增加新用户试用和生产接入成本。

medium 来源证据：Your AI needs an identity — here's how to fix that

可能增加新用户试用和生产接入成本。

medium 来源证据：memobase embedding模型维度不匹配

可能增加新用户试用和生产接入成本。

medium 来源证据：[Question] : user_event_gist 在执行插入是否有重复事件去重操作

可能增加新用户试用和生产接入成本。

Pitfall Log / 踩坑日志

项目：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

来源：Doramagic 发现、验证与编译记录

memobase 项目

Overview and Quickstart Guide

1. 项目定位与核心能力

2. 系统架构与数据流

3. 核心数据模型

4. 快速开始

4.1 部署服务端

4.2 启动 MCP 服务器

4.3 客户端调用示例

5. 画像抽取与合并机制

See Also

Backend Architecture and API Layer

后端架构与 API 层

整体系统架构

API 层与中间件

控制器与数据流

配置、提示词与客户端 SDK

常见开发路径

See Also

Client SDKs and MCP Integration

客户端 SDK 与 MCP 集成

概述

客户端 SDK 生态

Python SDK

Go SDK

TypeScript SDK

MCP 集成层

三大核心工具

客户端连接配置

配置、部署与使用模式

参见

LLM Integration and Memory Processing Pipeline

概述与设计目标

整体架构

核心阶段详解

1. 缓冲与批处理（Buffer）

2. 事实抽取（Extract）

3. 记忆合并（Merge / Merge-YOLO）

4. 画像整理与检索（Organize / Pick Related）

5. 事件摘要与打标（Event Summary & Tagging）

配置与可调参数

常见失败模式

See Also

失败模式与踩坑日记

Pitfall Log / 踩坑日志

1. 安装坑 · 来源证据：“add_user” and “update_user” handle additional data differently

2. 安装坑 · 来源证据：Your AI needs an identity — here's how to fix that

3. 安装坑 · 来源证据：memobase embedding模型维度不匹配

4. 配置坑 · 来源证据：[Question] : user_event_gist 在执行插入是否有重复事件去重操作

5. 能力坑 · 能力判断依赖假设

6. 运行坑 · 来源证据：search_event returns KeyError 'events'

7. 维护坑 · 维护活跃度未知

9. 安全/权限坑 · 存在评分风险

10. 安全/权限坑 · 来源证据：Error in get_embedding: Failed to embed texts: 404 page not found Traceback (most recent call last)

11. 维护坑 · issue/PR 响应质量未知

12. 维护坑 · 发布节奏不明确