1. 项目定位与核心能力

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

资料来源：README.md:1-30

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

2. 核心架构与数据模型

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

参见

• 项目 README
• memU-server 后端服务
• memU-ui 可视化面板
• API 文档
• LoComo 评估说明

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

1. 三层数据模型概览

memU 把记忆组织为"文件夹 + 文件 + 原材料"的三层结构，对应关系在 README.md 的 *The Compiled Workspace* 一节中有明确描述。

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)]

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

2. 记忆类型与提示模板

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

category_with_refs.py 用于在生成 MemoryCategory.summary 时，强制 LLM 在摘要语句中插入 [ref:ITEM_ID] 内联引用，把摘要中的每条结论追溯回具体的 MemoryItem——这是 v1.4.0 的特性。资料来源：category_with_refs.py

3. memorize() 写入流程

MemoryService.memorize() 是编译入口，README 用一个对称图把整条管线画了出来：raw files → extract → files + folders → persist。落入到代码层面，对应到 src/memu/app/memorize.py 与 src/memu/app/crud.py。

1. 预处理：document.py 的提示词把长文档压缩成"精炼正文 + 一句话 caption"，避免后续抽取阶段被噪声淹没。资料来源：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 与 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：

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

最小可运行的例子见 examples/sealos-assistant/README.md，它把 memorize / retrieve 包装为 HTTP 接口 /memorize、/recall，便于快速接入到任意 Agent 框架。

5. 已知问题与版本演进

资料来源：release v1.3.0、release v1.4.0、release v1.5.0、release v1.5.1

参见

• 存储后端与仓储实现：见 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/

概述

memU 通过两条"可插拔"轴线支撑其部署灵活性：存储侧以统一的 repository 契约让 in-memory、SQLite、Postgres 等后端可在不改动业务逻辑的前提下互换；模型侧通过 Profile-Based LLM Routing 把 chat、embedding、vision、transcription 等任务路由到不同提供商，并以 LLMBackend 抽象基类屏蔽各 HTTP 协议的差异（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）。

在 memorize 工作流中的位置

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

LLM/Embedding 路由架构

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

LLMBackend 抽象基类

src/memu/llm/backends/base.py 中定义的 LLMBackend 是所有提供商后端的根类：

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

• 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）
• 知识 / 行为 / 技能 / 工具 等记忆抽取（src/memu/prompts/memory_type/knowledge.py、src/memu/prompts/memory_type/behavior.py、src/memu/prompts/memory_type/skill.py、src/memu/prompts/memory_type/tool.py）
• 类别摘要（v1.4.0 起支持内联引用 [ref:ITEM_ID]）（src/memu/prompts/category_summary/category.py、src/memu/prompts/category_summary/category_with_refs.py）

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

LLM 响应处理

src/memu/app/memorize.py 中实现了对 LLM 输出的 XML 解析逻辑。当 LLM 返回非标准 XML（如多个并列 <item> 根元素触发 "junk after document element"）时，代码会用 <_root_> 合成根节点重试解析，使从不同 chat Profile 路由得到的结构化输出都能被稳定消费（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 四类任务的独立路由通道。

概述与运行时架构

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

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

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

常见故障与已知问题

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

部署与排障建议

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

2. 切换存储后端时的类型兼容。 SQLite 后端在 v1.2.0 引入后曾出现 embedding 列表无法被 SQLAlchemy 识别的问题（#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），在内部复现 LoCoMo 基准前应先确认评测入口已随发布版本一并提供。

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

兼容性里程碑

See Also

• README.md
• src/memu/prompts/memory_type/__init__.py
• src/memu/app/memorize.py
• src/memu/prompts/category_summary/category_with_refs.py

Pitfall Log / 踩坑日志

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