# https://github.com/NevaMind-AI/memU 项目说明书

生成时间：2026-06-24 00:09:21 UTC

## 目录

- [memU 概览与系统架构](#page-1)
- [核心数据模型与 memorize/retrieve API](#page-2)
- [可插拔存储后端与 LLM/Embedding 路由](#page-3)
- [部署、扩展、常见故障与已知问题](#page-4)

<a id='page-1'></a>

## memU 概览与系统架构

### 相关页面

相关主题：[核心数据模型与 memorize/retrieve API](#page-2), [可插拔存储后端与 LLM/Embedding 路由](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/NevaMind-AI/memU/blob/main/README.md)
- [src/memu/database/repositories/resource.py](https://github.com/NevaMind-AI/memU/blob/main/src/memu/database/repositories/resource.py)
- [src/memu/database/repositories/memory_category.py](https://github.com/NevaMind-AI/memU/blob/main/src/memu/database/repositories/memory_category.py)
- [src/memu/database/inmemory/repo.py](https://github.com/NevaMind-AI/memU/blob/main/src/memu/database/inmemory/repo.py)
- [src/memu/llm/backends/base.py](https://github.com/NevaMind-AI/memU/blob/main/src/memu/llm/backends/base.py)
- [src/memu/prompts/memory_type/skill.py](https://github.com/NevaMind-AI/memU/blob/main/src/memu/prompts/memory_type/skill.py)
- [src/memu/prompts/memory_type/knowledge.py](https://github.com/NevaMind-AI/memU/blob/main/src/memu/prompts/memory_type/knowledge.py)
- [src/memu/prompts/memory_type/behavior.py](https://github.com/NevaMind-AI/memU/blob/main/src/memu/prompts/memory_type/behavior.py)
- [src/memu/prompts/preprocess/document.py](https://github.com/NevaMind-AI/memU/blob/main/src/memu/prompts/preprocess/document.py)
- [src/memu/prompts/category_summary/__init__.py](https://github.com/NevaMind-AI/memU/blob/main/src/memu/prompts/category_summary/__init__.py)
</details>

# memU 概览与系统架构

## 1. 项目定位与核心能力

memU 是一个面向 AI 智能体（agent）的长期记忆工作区（workspace）运行时，其核心理念是把"原始资料"编译成结构化的"工作区"，再在需要时按需读取相关分层。它将对话日志、文档、部署记录、执行轨迹等异构资源统一抽取为六类强类型记忆：profile（画像）、event（事件）、knowledge（知识）、behavior（行为）、skill（技能）和 tool（工具）。`MemoryCategory`（类别文件夹）会随着新资料被注入而自动组织、交叉链接、嵌入并生成摘要，开发者无需手动打标签。`memorize()` 与 `retrieve()` 两个核心 API 均以字典形式返回，调用方可直接注入到任意 agent 工作流中。

资料来源：[README.md:1-30]()

典型使用场景包括：把聊天记录转换为用户偏好与目标（对话记忆）、把代码仓库文档与 PR 记录沉淀为可复用的项目记忆（编码智能体工作区上下文），以及更广泛地把任何原始资料转化为结构化、可追溯的智能体记忆。

## 2. 核心架构与数据模型

```mermaid
flowchart LR
    A[原始资源<br/>Resource] -->|preprocess| B[LLM 抽取]
    B --> C[MemoryItem<br/>profile/event/knowledge<br/>behavior/skill/tool]
    C --> D[MemoryCategory<br/>folder + summary + embedding]
    D --> E[(后端存储<br/>InMemory / SQLite / Postgres)]
    E -->|retrieve| F[按需读取<br/>相关分层]
    F --> G[Agent 工作流]

    H[LLM Backend<br/>base + provider] --> B
    I[Repository 契约<br/>ResourceRepo / MemoryCategoryRepo] --> E
```

memU 把数据模型抽象成三层，分别由对应的仓库接口（Protocol）约束：

- `Resource`——来源层，保存原始资源的 `url`、`modality`、`local_path`、`caption` 与 `embedding`。
- `MemoryItem`——记忆层，原子级、强类型，携带 `summary`、`extra`、`happened_at` 与 `embedding`。
- `MemoryCategory`——分类层，作为"文件夹"，维护 `name`、`description`、`summary`、`embedding` 以及下属的若干 `MemoryItem`。

这一模型同时被 in-memory、SQLite、Postgres 三种后端实现，确保调用方可以无侵入切换持久化方案。`InMemoryStore` 通过 `build_inmemory_models` 动态构建领域模型并把它们挂到 `InMemoryState` 上，从而在零依赖场景下也能完整跑通流程。

资料来源：[README.md:36-62]() [src/memu/database/repositories/resource.py:8-39]() [src/memu/database/repositories/memory_category.py:8-35]() [src/memu/database/inmemory/repo.py:19-39]()

## 3. 关键工作流：编译与读取

memU 把整个运行时浓缩为两个动作：

**编译（memorize）**：原始资源先经过预处理（`preprocess/document.py` 中的 prompt 负责生成浓缩版 + 一句话 `caption`），再交由各 `memory_type` 下的 prompt 模板抽取成结构化条目。`skill.py` 强调最小 300 字、frontmatter 必备、必须包含 Core Principles、Implementation Guide、Success Patterns、Common Pitfalls、Key Takeaways 等小节；`knowledge.py` 与 `behavior.py` 则要求每条 item 是一句独立的陈述性描述（< 50 词）、不能混入主观意见或一次性事件。抽取结果会被归入 `MemoryCategory`，并通过 `category_summary/category.py` 中的 prompt 增量更新类别摘要，支持 inline 引用（v1.4.0 引入）以及在 v1.5.0 加入的 `non-propagate` 选项。

**读取（retrieve）**：调用方传入 query 与 `where` 过滤条件，仓库层负责按 `user_id` / `agent_id` 等 scope 拉取相关 `MemoryCategory` 与 `MemoryItem`，并把 embedding 用于排序。返回的字典可直接喂给下游 LLM 或工具调用。

资料来源：[src/memu/prompts/memory_type/skill.py:1-30]() [src/memu/prompts/memory_type/knowledge.py:1-25]() [src/memu/prompts/memory_type/behavior.py:1-25]() [src/memu/prompts/preprocess/document.py:1-15]() [src/memu/prompts/category_summary/__init__.py:1-10]()

## 4. 可插拔后端与可配置 LLM

`memu.llm.backends.base.LLMBackend` 为所有 HTTP LLM provider 提供统一抽象：默认走 OpenAI 风格的 `Authorization: Bearer` 头，子类按需覆盖 `default_headers`、`build_summary_payload`、`parse_summary_response` 与 `build_vision_payload`。配合配置层（profile-based routing）即可在聊天、嵌入、视觉、语音转写之间路由不同的 LLM profile。v1.5.0 起还新增了 LLM 与 embedding client 的 HTTP 代理支持。

资料来源：[src/memu/llm/backends/base.py:7-46]()

## 5. 社区反馈与已知问题

- `happened_at` 写入为 NULL（[#428](https://github.com/NevaMind-AI/memU/issues/428)）：在 `MemoryService.memorize` 处理对话数据时，即使消息携带时间戳，DB 列仍可能存为 NULL，提示抽取→持久化之间的字段映射仍需加固。
- `memu-server` 入口指向不存在的 `memu.server.cli` 模块（[#354](https://github.com/NevaMind-AI/memU/issues/354)）：`pyproject.toml` 中的 console script 与仓库实际布局不一致。
- SQLite 后端 embedding 字段类型错误（[#382](https://github.com/NevaMind-AI/memU/issues/382)）：SQLAlchemy 抛 `ValueError: <class 'list'> has no matching SQLAlchemy type`，需要在 SQLite 方言中显式声明 `JSON` / `BLOB` 适配。
- 删除记忆功能（[#42](https://github.com/NevaMind-AI/memU/issues/42)）：v1.2.0 引入 `clear memory`，但客户端 SDK 需配合 `delete_memories` 才可按用户/agent 维度清理。
- 评估脚本与 LoComo 复现（[#37](https://github.com/NevaMind-AI/memU/issues/37)）、Linux 支持（[#304](https://github.com/NevaMind-AI/memU/issues/304)）与认知架构理论提案（[#337](https://github.com/NevaMind-AI/memU/issues/337)）是社区持续关注的方向。

## 参见

- [项目 README](https://github.com/NevaMind-AI/memU/blob/main/README.md)
- [memU-server 后端服务](https://github.com/NevaMind-AI/memU-server)
- [memU-ui 可视化面板](https://github.com/NevaMind-AI/memU-ui)
- [API 文档](https://memu.pro/docs)
- [LoComo 评估说明](https://github.com/NevaMind-AI/memU-experiment)

---

<a id='page-2'></a>

## 核心数据模型与 memorize/retrieve API

### 相关页面

相关主题：[memU 概览与系统架构](#page-1), [可插拔存储后端与 LLM/Embedding 路由](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/memu/app/memorize.py](https://github.com/NevaMind-AI/memU/blob/main/src/memu/app/memorize.py)
- [src/memu/app/retrieve.py](https://github.com/NevaMind-AI/memU/blob/main/src/memu/app/retrieve.py)
- [src/memu/app/crud.py](https://github.com/NevaMind-AI/memU/blob/main/src/memu/app/crud.py)
- [src/memu/database/models.py](https://github.com/NevaMind-AI/memU/blob/main/src/memu/database/models.py)
- [src/memu/database/repositories/memory_item.py](https://github.com/NevaMind-AI/memU/blob/main/src/memu/database/repositories/memory_item.py)
- [src/memu/database/repositories/memory_category.py](https://github.com/NevaMind-AI/memU/blob/main/src/memu/database/repositories/memory_category.py)
- [src/memu/prompts/memory_type/profile.py](https://github.com/NevaMind-AI/memU/blob/main/src/memu/prompts/memory_type/profile.py)
- [src/memu/prompts/memory_type/event.py](https://github.com/NevaMind-AI/memU/blob/main/src/memu/prompts/memory_type/event.py)
- [src/memu/prompts/memory_type/knowledge.py](https://github.com/NevaMind-AI/memU/blob/main/src/memu/prompts/memory_type/knowledge.py)
- [src/memu/prompts/memory_type/behavior.py](https://github.com/NevaMind-AI/memU/blob/main/src/memu/prompts/memory_type/behavior.py)
- [src/memu/prompts/memory_type/skill.py](https://github.com/NevaMind-AI/memU/blob/main/src/memu/prompts/memory_type/skill.py)
- [src/memu/prompts/memory_type/tool.py](https://github.com/NevaMind-AI/memU/blob/main/src/memu/prompts/memory_type/tool.py)
- [src/memu/prompts/category_summary/category_with_refs.py](https://github.com/NevaMind-AI/memU/blob/main/src/memu/prompts/category_summary/category_with_refs.py)
- [src/memu/prompts/preprocess/document.py](https://github.com/NevaMind-AI/memU/blob/main/src/memu/prompts/preprocess/document.py)
- [README.md](https://github.com/NevaMind-AI/memU/blob/main/README.md)
- [examples/sealos-assistant/README.md](https://github.com/NevaMind-AI/memU/blob/main/examples/sealos-assistant/README.md)
</details>

# 核心数据模型与 memorize/retrieve API

memU 是一套面向 AI Agent 的"长期记忆"中间层，核心思想是把异构原始资料（对话、文档、日志）编译成可检索的"工作空间"（workspace），再按需把相关层喂回 Agent。本页围绕三层核心数据模型 `MemoryCategory` / `MemoryItem` / `Resource` 以及对外的两个主入口 `MemoryService.memorize()` 与 `MemoryService.retrieve()` 展开。

## 1. 三层数据模型概览

memU 把记忆组织为"文件夹 + 文件 + 原材料"的三层结构，对应关系在 [README.md](https://github.com/NevaMind-AI/memU/blob/main/README.md) 的 *The Compiled Workspace* 一节中有明确描述。

```mermaid
graph TD
    R[Resource<br/>url / modality / local_path<br/>caption / embedding] --> M[MemoryItem<br/>memory_type · summary<br/>extra · happened_at · embedding]
    M --> C[MemoryCategory<br/>name · description<br/>summary · embedding]
    C --> W[(Workspace<br/>memorize / retrieve)]
```

| 层级 | 文件系统类比 | 关键字段 | 用途 |
|------|-------------|----------|------|
| `MemoryCategory` | 文件夹 | `name`、`description`、`summary`、`embedding` | 聚合同主题记忆，对外暴露"主题级摘要"以便做广度检索 |
| `MemoryItem` | 文件 | `memory_type`、`summary`、`extra`、`happened_at`、`embedding` | 原子化的事实/偏好/事件/技能条目，被精确注入 Agent 上下文 |
| `Resource` | 原材料 | `url`、`modality`、`local_path`、`caption`、`embedding` | 记忆的来源溯源（聊天文件、文档、日志等） |

各层都携带 `embedding` 字段，意味着所有层级都可参与向量召回。`MemoryItem` 引入 `happened_at`（事件时间戳）和 `extra`（可扩展字典）是在 v1.3.0 显式加入的，用于承载"何时发生"以及"无法归入主字段的元信息"。资料来源：[README.md](https://github.com/NevaMind-AI/memU/blob/main/README.md)

## 2. 记忆类型与提示模板

`MemoryItem.memory_type` 是一个枚举，README 与提示模板目录都指向六种内置类型：`profile`、`event`、`knowledge`、`behavior`、`skill`、`tool`。每种类型都有一份独立的抽取 Prompt（`src/memu/prompts/memory_type/*.py`），用来约束 LLM 在 `memorize()` 阶段产出的内容形态。

| 类型 | 提示模板 | 抽取目标 | 关键约束 |
|------|---------|---------|---------|
| `profile` | [profile.py](https://github.com/NevaMind-AI/memU/blob/main/src/memu/prompts/memory_type/profile.py) | 用户的稳定属性、自我披露的事实 | 必须用陈述句；剔除助手侧的猜测、天气等临时信息 |
| `event` | [event.py](https://github.com/NevaMind-AI/memU/blob/main/src/memu/prompts/memory_type/event.py) | 发生在特定时间、涉及用户的事件 | 必须有时间/地点/参与者；只保留用户亲述 |
| `knowledge` | [knowledge.py](https://github.com/NevaMind-AI/memU/blob/main/src/memu/prompts/memory_type/knowledge.py) | 客观事实、概念、定义 | 单句陈述；不超过约 50 词；禁止主观意见 |
| `behavior` | [behavior.py](https://github.com/NevaMind-AI/memU/blob/main/src/memu/prompts/memory_type/behavior.py) | 行为模式、惯常解法 | 必须是反复出现的模式；一次性动作不计入 |
| `skill` | [skill.py](https://github.com/NevaMind-AI/memU/blob/main/src/memu/prompts/memory_type/skill.py) | 可复用的技能/工具模式 | 输出完整 Markdown Skill 文档，含 frontmatter 且 ≥ 300 词 |
| `tool` | [tool.py](https://github.com/NevaMind-AI/memU/blob/main/src/memu/prompts/memory_type/tool.py) | 工具调用模式与 `when_to_use` | 必须标注工具名、场景与结果 |

`category_with_refs.py` 用于在生成 `MemoryCategory.summary` 时，强制 LLM 在摘要语句中插入 `[ref:ITEM_ID]` 内联引用，把摘要中的每条结论追溯回具体的 `MemoryItem`——这是 v1.4.0 的特性。资料来源：[category_with_refs.py](https://github.com/NevaMind-AI/memU/blob/main/src/memu/prompts/category_summary/category_with_refs.py)

## 3. memorize() 写入流程

`MemoryService.memorize()` 是**编译**入口，README 用一个对称图把整条管线画了出来：raw files → extract → files + folders → persist。落入到代码层面，对应到 [src/memu/app/memorize.py](https://github.com/NevaMind-AI/memU/blob/main/src/memu/app/memorize.py) 与 [src/memu/app/crud.py](https://github.com/NevaMind-AI/memU/blob/main/src/memu/app/crud.py)。

1. **预处理**：`document.py` 的提示词把长文档压缩成"精炼正文 + 一句话 caption"，避免后续抽取阶段被噪声淹没。资料来源：[document.py](https://github.com/NevaMind-AI/memU/blob/main/src/memu/prompts/preprocess/document.py)
2. **多类型抽取**：按 `modality` 选择合适的记忆类型 Prompt 并行调用 LLM，得到 `memories_items` 列表（每条都带 `content` 与 `categories`）。
3. **归类与建立关系**：每条 `MemoryItem` 关联到既有或新建的 `MemoryCategory`，并按 LLM 摘要挂到对应文件夹下。
4. **嵌入与摘要**：为 `Resource` / `MemoryItem` / `MemoryCategory` 写入 `embedding`；调用 `category_with_refs.py` 生成带 `[ref:...]` 的可追溯摘要。
5. **持久化**：通过 [memory_item.py](https://github.com/NevaMind-AI/memU/blob/main/src/memu/database/repositories/memory_item.py) 与 [memory_category.py](https://github.com/NevaMind-AI/memU/blob/main/src/memu/database/repositories/memory_category.py) 仓库接口写入后端，底层可插拔 in-memory / SQLite / Postgres。

v1.5.0 引入的 *non-propagate option* 让调用方可以在 patch 记忆时禁止级联更新（提交 `3b67458`），用于"只修正本地条目、不动父级摘要"的细粒度场景。

## 4. retrieve() 检索流程

`MemoryService.retrieve()` 是**服务**入口，README 描述的流程是 `query → walk folders → ranked files`。对应到 [src/memu/app/retrieve.py](https://github.com/NevaMind-AI/memU/blob/main/src/memu/app/retrieve.py)：

- **范围过滤**：调用方通过 `where={"user_id": "..."}` 等条件限定召回范围（用户、Agent、Session、Task）。
- **文件夹导航**：先在 `MemoryCategory` 层做粗筛，命中主题后下钻。
- **项目排序**：在 `MemoryItem` 层做精细排序，综合 `embedding` 相似度与摘要相关性。
- **回包结构**：返回字典形式的 `MemoryCategory` 列表，必要时附带 `inline_refs` 字段，方便 Agent 解释"这条结论来自哪条 Item"。

最小可运行的例子见 [examples/sealos-assistant/README.md](https://github.com/NevaMind-AI/memU/blob/main/examples/sealos-assistant/README.md)，它把 `memorize` / `retrieve` 包装为 HTTP 接口 `/memorize`、`/recall`，便于快速接入到任意 Agent 框架。

## 5. 已知问题与版本演进

| 现象 | 版本/提交 | 备注 |
|------|----------|------|
| `memory_items.happend_at` 即使传入合法时间戳也存为 `NULL` | 见 issue #428 | 字段在 v1.3.0（提交 `77938e9`）新增，需要核对写入路径是否正确读取 `extra`/消息时间戳 |
| SQLite 后端 `embedding` 字段触发 `ValueError: <class 'list'> has no matching SQLAlchemy type` | 见 issue #382 | 发生在 2026-03-13 的 main 分支，需要把 `embedding` 显式声明为 `JSON`/原生向量列 |
| `memu-server` 入口指向不存在的 `memu.server.cli` 模块 | 见 issue #354 | `pyproject.toml` 中的 `[project.scripts]` 与源码不一致；需补齐 `src/memu/server/cli.py` |
| alembic URL 插值错误 | v1.5.1（提交 `fd87ceb`） | 已修复迁移脚本的字符串插值 |

资料来源：[release v1.3.0](https://github.com/NevaMind-AI/memU/releases/tag/v1.3.0)、[release v1.4.0](https://github.com/NevaMind-AI/memU/releases/tag/v1.4.0)、[release v1.5.0](https://github.com/NevaMind-AI/memU/releases/tag/v1.5.0)、[release v1.5.1](https://github.com/NevaMind-AI/memU/releases/tag/v1.5.1)

## 参见

- 存储后端与仓储实现：见 [src/memu/database/repositories/](https://github.com/NevaMind-AI/memU/tree/main/src/memu/database/repositories) 下的 `memory_item.py`、`memory_category.py` 与 `resource.py`
- 自定义 LLM / Embedding Provider：见 `src/memu/llm/` 目录
- 评测脚本：见 `memU/scripts/evals/locomo/`（社区请求复现脚本，见 issue #37）
- 端到端示例：见 [examples/sealos-assistant/](https://github.com/NevaMind-AI/memU/tree/main/examples/sealos-assistant)

---

<a id='page-3'></a>

## 可插拔存储后端与 LLM/Embedding 路由

### 相关页面

相关主题：[memU 概览与系统架构](#page-1), [核心数据模型与 memorize/retrieve API](#page-2), [部署、扩展、常见故障与已知问题](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/NevaMind-AI/memU/blob/main/README.md)
- [src/memu/llm/backends/base.py](https://github.com/NevaMind-AI/memU/blob/main/src/memu/llm/backends/base.py)
- [src/memu/app/memorize.py](https://github.com/NevaMind-AI/memU/blob/main/src/memu/app/memorize.py)
- [src/memu/prompts/preprocess/document.py](https://github.com/NevaMind-AI/memU/blob/main/src/memu/prompts/preprocess/document.py)
- [src/memu/prompts/memory_type/knowledge.py](https://github.com/NevaMind-AI/memU/blob/main/src/memu/prompts/memory_type/knowledge.py)
- [src/memu/prompts/memory_type/behavior.py](https://github.com/NevaMind-AI/memU/blob/main/src/memu/prompts/memory_type/behavior.py)
- [src/memu/prompts/memory_type/skill.py](https://github.com/NevaMind-AI/memU/blob/main/src/memu/prompts/memory_type/skill.py)
- [src/memu/prompts/memory_type/tool.py](https://github.com/NevaMind-AI/memU/blob/main/src/memu/prompts/memory_type/tool.py)
- [src/memu/prompts/category_summary/category.py](https://github.com/NevaMind-AI/memU/blob/main/src/memu/prompts/category_summary/category.py)
- [src/memu/prompts/category_summary/category_with_refs.py](https://github.com/NevaMind-AI/memU/blob/main/src/memu/prompts/category_summary/category_with_refs.py)
</details>

# 可插拔存储后端与 LLM/Embedding 路由

## 概述

memU 通过两条"可插拔"轴线支撑其部署灵活性：存储侧以统一的 repository 契约让 in-memory、SQLite、Postgres 等后端可在不改动业务逻辑的前提下互换；模型侧通过 Profile-Based LLM Routing 把 chat、embedding、vision、transcription 等任务路由到不同提供商，并以 `LLMBackend` 抽象基类屏蔽各 HTTP 协议的差异（[README.md](https://github.com/NevaMind-AI/memU/blob/main/README.md)）。这两条轴线在 `MemoryService.memorize` / `retrieve` 工作流中协同工作。

## 可插拔存储后端

### 支持的后端

README 在功能总览中明确列出三类后端：

> 🧱 **Pluggable Storage** | Use in-memory, SQLite, or Postgres backends with the same repository contracts

这意味着 `MemoryCategory`、`MemoryItem`、`Resource` 等核心记录都通过同一组 repository 接口访问，具体后端实现由启动配置注入，业务层不感知底层差异（[README.md](https://github.com/NevaMind-AI/memU/blob/main/README.md)）。

### 在 memorize 工作流中的位置

`memorize()` 处理链"抽取 → 整理 → 持久化"中的最后一步"持久化"即落到可插拔仓储层。开发者可在 in-memory（实验）、SQLite（单机）、Postgres（生产）之间仅通过配置切换，无需重写抽取与组织逻辑（[README.md](https://github.com/NevaMind-AI/memU/blob/main/README.md)）。

## LLM/Embedding 路由架构

```mermaid
flowchart LR
    A[MemoryService] --> B[Profile 配置]
    B --> C1[chat profile]
    B --> C2[embedding profile]
    B --> C3[vision profile]
    B --> C4[transcription profile]
    C1 --> D[LLMBackend 抽象]
    C2 --> D
    C3 --> D
    C4 --> D
    D --> E1[OpenAI]
    D --> E2[Anthropic]
    D --> E3[其它提供商]
```

### Profile-Based 路由

README 在特性中列出：

> 🔀 **Profile-Based LLM Routing** | Route chat, embedding, vision, and transcription work through configurable LLM profiles

不同任务通过独立 Profile 配置，可指向不同模型或不同提供商，互不干扰（[README.md](https://github.com/NevaMind-AI/memU/blob/main/README.md)）。

### LLMBackend 抽象基类

[src/memu/llm/backends/base.py](https://github.com/NevaMind-AI/memU/blob/main/src/memu/llm/backends/base.py) 中定义的 `LLMBackend` 是所有提供商后端的根类：

```python
class LLMBackend:
    name: str = "base"
    summary_endpoint: str = "/chat/completions"

    def default_headers(self, api_key: str) -> dict[str, str]:
        return {"Authorization": f"Bearer {api_key}"}
```

关键设计点（[src/memu/llm/backends/base.py](https://github.com/NevaMind-AI/memU/blob/main/src/memu/llm/backends/base.py)）：

- `name` 与 `summary_endpoint` 标识后端身份与默认 chat endpoint。
- `default_headers` 默认采用 OpenAI 风格 `Bearer` 鉴权；其它鉴权方案（如 Anthropic 的 `x-api-key`）由子类重写。
- `build_summary_payload` / `parse_summary_response` 抽象方法处理对话总结请求的序列化与反序列化。
- `build_vision_payload` 抽象方法处理多模态视觉请求。

模块注释还指出："Each provider lives in its own module under `:mod:memu.llm.backends` and customizes the request endpoint, payload shape, response parsing and (when needed) the auth headers"，即所有具体提供商都按此契约扩展。

### 路由到的具体 LLM 任务

在 `memorize` 流程中，chat 通道会按记忆类型与处理阶段分发到专用 prompt，再经由 chat Profile 路由到具体模型：

- 文档预处理 condense + caption（[src/memu/prompts/preprocess/document.py](https://github.com/NevaMind-AI/memU/blob/main/src/memu/prompts/preprocess/document.py)）
- 知识 / 行为 / 技能 / 工具 等记忆抽取（[src/memu/prompts/memory_type/knowledge.py](https://github.com/NevaMind-AI/memU/blob/main/src/memu/prompts/memory_type/knowledge.py)、[src/memu/prompts/memory_type/behavior.py](https://github.com/NevaMind-AI/memU/blob/main/src/memu/prompts/memory_type/behavior.py)、[src/memu/prompts/memory_type/skill.py](https://github.com/NevaMind-AI/memU/blob/main/src/memu/prompts/memory_type/skill.py)、[src/memu/prompts/memory_type/tool.py](https://github.com/NevaMind-AI/memU/blob/main/src/memu/prompts/memory_type/tool.py)）
- 类别摘要（v1.4.0 起支持内联引用 `[ref:ITEM_ID]`）（[src/memu/prompts/category_summary/category.py](https://github.com/NevaMind-AI/memU/blob/main/src/memu/prompts/category_summary/category.py)、[src/memu/prompts/category_summary/category_with_refs.py](https://github.com/NevaMind-AI/memU/blob/main/src/memu/prompts/category_summary/category_with_refs.py)）

这些 chat 任务最终都通过 `LLMBackend` 走 HTTP 出站。

### LLM 响应处理

[src/memu/app/memorize.py](https://github.com/NevaMind-AI/memU/blob/main/src/memu/app/memorize.py) 中实现了对 LLM 输出的 XML 解析逻辑。当 LLM 返回非标准 XML（如多个并列 `<item>` 根元素触发 "junk after document element"）时，代码会用 `<_root_>` 合成根节点重试解析，使从不同 chat Profile 路由得到的结构化输出都能被稳定消费（[src/memu/app/memorize.py](https://github.com/NevaMind-AI/memU/blob/main/src/memu/app/memorize.py)）。

## 已知问题与版本演进

社区反馈的问题集中在存储与外部依赖接入侧：

- **SQLite 嵌入向量类型不匹配**（issue #382）：SQLite 后端的 `embedding` 字段（Python `list`）在 SQLAlchemy 映射时无法匹配内置类型，触发 `ValueError: <class 'list'> has no matching SQLAlchemy type`，需以自定义 `TypeDecorator` 显式转换。
- **Alembic URL 插值修复**（v1.5.1, PR #390）：修复 alembic `url` 的插值逻辑，使 SQLite/Postgres 后端在迁移时 URL 正确展开。
- **HTTP 代理支持**（v1.5.0）：LLM 与 Embedding 客户端新增 HTTP 代理支持，便于受限网络环境路由出站请求。
- **SQLite 存储后端首次引入**（v1.2.0, PR #201）：从该版本起，SQLite 与 in-memory、Postgres 并列成为一等后端。

## 小结

可插拔存储与 LLM 路由共同构成 memU 的部署灵活性骨架：前者通过 repository 契约隔离物理存储，使 in-memory / SQLite / Postgres 可热替换；后者通过 `LLMBackend` 与 Profile 配置隔离模型提供商，并提供 chat、embedding、vision、transcription 四类任务的独立路由通道。

---

<a id='page-4'></a>

## 部署、扩展、常见故障与已知问题

### 相关页面

相关主题：[memU 概览与系统架构](#page-1), [核心数据模型与 memorize/retrieve API](#page-2), [可插拔存储后端与 LLM/Embedding 路由](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/NevaMind-AI/memU/blob/main/README.md)
- [src/memu/prompts/memory_type/__init__.py](https://github.com/NevaMind-AI/memU/blob/main/src/memu/prompts/memory_type/__init__.py)
- [src/memu/prompts/memory_type/profile.py](https://github.com/NevaMind-AI/memU/blob/main/src/memu/prompts/memory_type/profile.py)
- [src/memu/prompts/memory_type/knowledge.py](https://github.com/NevaMind-AI/memU/blob/main/src/memu/prompts/memory_type/knowledge.py)
- [src/memu/prompts/memory_type/behavior.py](https://github.com/NevaMind-AI/memU/blob/main/src/memu/prompts/memory_type/behavior.py)
- [src/memu/prompts/memory_type/skill.py](https://github.com/NevaMind-AI/memU/blob/main/src/memu/prompts/memory_type/skill.py)
- [src/memu/prompts/preprocess/document.py](https://github.com/NevaMind-AI/memU/blob/main/src/memu/prompts/preprocess/document.py)
- [src/memu/prompts/category_summary/category.py](https://github.com/NevaMind-AI/memU/blob/main/src/memu/prompts/category_summary/category.py)
- [src/memu/prompts/category_summary/category_with_refs.py](https://github.com/NevaMind-AI/memU/blob/main/src/memu/prompts/category_summary/category_with_refs.py)
- [src/memu/app/memorize.py](https://github.com/NevaMind-AI/memU/blob/main/src/memu/app/memorize.py)
</details>

# 部署、扩展、常见故障与已知问题

## 概述与运行时架构

memU 是一个面向 LLM 智能体的可插拔记忆框架，提供 `memorize()`（编译写入）与 `retrieve()`（按需读取）两个核心运行入口。运行时将原始资源抽取为类型化记忆项（profile / event / knowledge / behavior / skill / tool），并组织到 `MemoryCategory` 文件夹与 `MemoryItem` 文件的层级结构中，最终落盘到可插拔后端。资料来源：[README.md]()

后端存储层是部署与扩展的关键接缝。README 明确指出"可插拔存储"支持 in-memory、SQLite 与 Postgres 三种后端，且都遵循同一组 repository 契约，这意味着在生产环境中切换持久化方案不需要重写上层逻辑。LLM 调用层则通过 profile 路由，使聊天、嵌入、视觉、语音转写任务可以分别指向不同的模型配置。资料来源：[README.md]()

```mermaid
flowchart LR
    A[原始资源<br/>chat / doc / log] --> B[preprocess<br/>document.py]
    B --> C[memory_type 抽取<br/>profile/knowledge/behavior/skill]
    C --> D[MemoryItem + MemoryCategory]
    D --> E[可插拔后端<br/>in-memory / SQLite / Postgres]
    D --> F[category_summary<br/>category.py / category_with_refs.py]
    F --> G[retrieve() 返回索引化上下文]
```

## 扩展点与自定义方式

### 记忆类型扩展

`src/memu/prompts/memory_type/__init__.py` 暴露了记忆类型系统的注册表与默认提示词，可用于新增自定义 `memory_type`。该模块导出了 `CUSTOM_PROMPTS`、`CUSTOM_TYPE_CUSTOM_PROMPTS`、`DEFAULT_MEMORY_CUSTOM_PROMPT_ORDINAL`、`DEFAULT_MEMORY_TYPES` 与 `PROMPTS` 五个公开符号，扩展时需遵循 `workflow / rules / category / output` 等块的顺序约定（ordinal 10–90）。资料来源：[src/memu/prompts/memory_type/__init__.py]()

### 抽取 Prompt 的结构化组织

每种内置记忆类型都遵循相同的"目标 → 工作流 → 规则 → 类别 → 输出"五段结构。`profile.py` 强调"使用 'the user' 引用用户"、"避免记录临时性信息"，并要求每条记忆自包含、可独立理解。资料来源：[src/memu/prompts/memory_type/profile.py]() `knowledge.py` 进一步要求"客观事实"、拒绝主观意见与个人经历，且每条不超过 50 词。资料来源：[src/memu/prompts/memory_type/knowledge.py]() `behavior.py` 限定为"重复出现的模式与例程"，排除一次性事件。资料来源：[src/memu/prompts/memory_type/behavior.py]() `skill.py` 则要求产出 300 词以上的可独立引用技能档案。资料来源：[src/memu/prompts/memory_type/skill.py]()

### 类别摘要与引用

`category_summary/category_with_refs.py` 在合并新条目时强制嵌入 `[ref:ITEM_ID]` 内联引用，从而保证摘要语句可追溯到源记忆项。资料来源：[src/memu/prompts/category_summary/category_with_refs.py]() `category.py` 则规定了去重、冲突解决与"一次性事件剔除"等合并规则。资料来源：[src/memu/prompts/category_summary/category.py]()

## 常见故障与已知问题

下表汇总了社区与发布说明中记录的主要问题，便于在升级与排障时快速对照：

| 问题编号 | 现象 | 受影响版本 / 模块 | 修复版本 / 说明 |
|---|---|---|---|
| [#354](https://github.com/NevaMind-AI/memU/issues/354) | `memu-server` 入口指向缺失模块 `memu.server.cli` | main 分支 | 需补齐 `src/memu/server/cli.py` 或修正 `pyproject.toml` 中的 `project.scripts` |
| [#382](https://github.com/NevaMind-AI/memU/issues/382) | SQLite 后端对 `embedding` 字段报 `ValueError: <class 'list'> has no matching SQLAlchemy type` | main 2026-03-13 | 需为 `embedding` 列显式声明 `JSON`/`pickleType` 类型映射 |
| [#390](https://github.com/NevaMind-AI/memU/issues/390) | Alembic URL 字符串插值错误 | v1.5.0 | v1.5.1 修正（commit fd87ceb） |
| [#428](https://github.com/NevaMind-AI/memU/issues/428) | `memory_items.happend_at` 字段即使消息携带时间戳仍存为 NULL | v1.3.0 引入 `happened_at` 字段后 | 需在抽取流程中显式回填 `happened_at`，检查消息 schema 是否含 `created_at`/`timestamp` 字段 |
| [#304](https://github.com/NevaMind-AI/memU/issues/304) | Linux 平台兼容性诉求 | — | v1.1.0 起增加 Linux ARM64 (aarch64) 构建目标 |

## 部署与排障建议

**1. 升级前核对 schema 变更。** v1.3.0 为 `MemoryItem` 引入了 `happened_at` 与 `extra` 字段（[release notes](https://github.com/NevaMind-AI/memU/releases/tag/v1.3.0)），从旧版本升级时必须执行 Alembic 迁移；若该列持续为 NULL，应检查 `memorize()` 流程是否将消息级 `timestamp`/`created_at` 正确映射至 item 级 `happened_at`。

**2. 切换存储后端时的类型兼容。** SQLite 后端在 v1.2.0 引入后曾出现 `embedding` 列表无法被 SQLAlchemy 识别的问题（[#382](https://github.com/NevaMind-AI/memU/issues/382)）。生产环境切换到 SQLite 之前，应先在仓库模型层确认向量字段已注册为可序列化类型。Postgres 后端则受益于原生 `JSONB`/`ARRAY` 类型，通常无需额外处理。

**3. 抽取层的容错。** `src/memu/app/memorize.py` 的 XML 解析对"多个并列 `<item>` 顶层元素"做了兜底：先用 `ET.fromstring` 解析，失败时再包一层合成根 `<_root_>` 重试。这意味着即便 LLM 输出格式偶发漂移，记忆抽取仍能继续。资料来源：[src/memu/app/memorize.py]() 部署监控应同时采集 `Failed to parse XML` 与 `Could not find valid root tag` 两类告警。

**4. 文档预处理。** `preprocess/document.py` 要求模型产出 `<processed_content>` 与 `<caption>` 两段结构化结果，部署时若更换为较小上下文窗口的模型，可能出现 caption 超长或 processed_content 截断，需在调用前进行 token 预算校验。资料来源：[src/memu/prompts/preprocess/document.py]()

**5. 评估脚本可复现性。** 社区已多次请求公开 `memU/scripts/evals/locomo` 的评估脚本（[#37](https://github.com/NevaMind-AI/memU/issues/37)），在内部复现 LoCoMo 基准前应先确认评测入口已随发布版本一并提供。

**6. 入口脚本一致性。** `memu-server` 入口在 main 分支曾指向未实现的 `memu.server.cli`（[#354](https://github.com/NevaMind-AI/memU/issues/354)），从源码安装后若 CLI 启动失败，应优先核查 `pyproject.toml` 的 `[project.scripts]` 与 `src/memu/server/` 目录是否同步。

## 兼容性里程碑

| 版本 | 关键变更 | 资料来源 |
|---|---|---|
| v1.0.0 | 首个稳定版，BREAKING CHANGES | [release](https://github.com/NevaMind-AI/memU/releases/tag/v1.0.0) |
| v1.1.0 | 新增 Linux ARM64 (aarch64) 构建 | [release](https://github.com/NevaMind-AI/memU/releases/tag/v1.1.0) |
| v1.2.0 | 新增 SQLite 后端、`clear memory` 接口 | [release](https://github.com/NevaMind-AI/memU/releases/tag/v1.2.0) |
| v1.3.0 | 引入 `happened_at` 与 `extra` 字段 | [release](https://github.com/NevaMind-AI/memU/releases/tag/v1.3.0) |
| v1.4.0 | 类别摘要支持内联引用 | [release](https://github.com/NevaMind-AI/memU/releases/tag/v1.4.0) |
| v1.5.0 | 新增 memory patch `non_propagate`、HTTP 代理 | [release](https://github.com/NevaMind-AI/memU/releases/tag/v1.5.0) |
| v1.5.1 | 修正 Alembic URL 插值 | [release](https://github.com/NevaMind-AI/memU/releases/tag/v1.5.1) |

## See Also

- [README.md](https://github.com/NevaMind-AI/memU/blob/main/README.md)
- [src/memu/prompts/memory_type/__init__.py](https://github.com/NevaMind-AI/memU/blob/main/src/memu/prompts/memory_type/__init__.py)
- [src/memu/app/memorize.py](https://github.com/NevaMind-AI/memU/blob/main/src/memu/app/memorize.py)
- [src/memu/prompts/category_summary/category_with_refs.py](https://github.com/NevaMind-AI/memU/blob/main/src/memu/prompts/category_summary/category_with_refs.py)

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：NevaMind-AI/memU

摘要：发现 10 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：配置坑 - 来源证据：[BUG] memory_items table's happend_at collumn stores NULL value even though when proper timestamp provided in messages.。

## 1. 配置坑 · 来源证据：[BUG] memory_items table's happend_at collumn stores NULL value even though when proper timestamp provided in messages.

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[BUG] memory_items table's happend_at collumn stores NULL value even though when proper timestamp provided in messages.
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/NevaMind-AI/memU/issues/428 | 来源类型 github_issue 暴露的待验证使用条件。

## 2. 安装坑 · 来源证据：Bug: memu-server entry point points to missing module (memu.server.cli)

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Bug: memu-server entry point points to missing module (memu.server.cli)
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/NevaMind-AI/memU/issues/354 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 3. 安装坑 · 来源证据：[BUG] sqlite backend embding issue

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[BUG] sqlite backend embding issue
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/NevaMind-AI/memU/issues/382 | 来源类型 github_issue 暴露的待验证使用条件。

## 4. 配置坑 · 可能修改宿主 AI 配置

- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 证据：capability.host_targets | https://github.com/NevaMind-AI/memU | host_targets=openclaw, mcp_host, claude

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

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/NevaMind-AI/memU | README/documentation is current enough for a first validation pass.

## 6. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/NevaMind-AI/memU | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/NevaMind-AI/memU | no_demo; severity=medium

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

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/NevaMind-AI/memU | no_demo; severity=medium

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

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/NevaMind-AI/memU | issue_or_pr_quality=unknown

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

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/NevaMind-AI/memU | release_recency=unknown

<!-- canonical_name: NevaMind-AI/memU; human_manual_source: deepwiki_human_wiki -->