如果你觉得 memU 有用或有趣，欢迎点个 GitHub Star ⭐️。
---
## ✨ Core Features
| Capability | Description |
|------------|-------------|
| 🗂️ **Multimodal Ingestion** | 将对话、文档、图片、视频、音频、URL、日志和本地文件写入记忆 |
| 📁 **Compiled Memory Workspace** | 持久化 Index、Skill 和 Memory 层 — 文件夹（categories）、文件（items）、源工件、链接、摘要和嵌入 |
| 🧠 **Typed Memory Extraction** | 从原始源中提取 profile、event、knowledge、behavior、skill 和 tool 记忆 |
| 🛠️ **Self-Evolving Skills** | 从 agent 轨迹中自动提取可复用的工具模式与工作流，并在每次工作区同步时合并精炼，而非重新学习 |
| 🧭 **Self-Organizing Folders** | 自动构建 categories、链接、摘要和嵌入，无需手动打标签 |
| 🤖 **Agent-Ready Retrieval** | 无需 LLM 的 `retrieve_workspace()` 直接对记忆片段、文件和源资源进行排序 |
| 🔄 **Incremental Workspace Sync** | `memorize_workspace()` 将文件夹与 manifest 进行 diff — 仅（重新）处理已变更文件，删除操作级联生效 |
| 🧱 **Pluggable Storage** | 使用内存、SQLite 或 Postgres 后端，共享同一套 repository 契约 |
| 🔀 **Profile-Based LLM Routing** | 通过可配置的 LLM profiles 路由聊天、嵌入、视觉和转录任务 |
| ⌨️ **CLI** | `memu` 命令（pip）和 `npx memu-cli`（npm）— 在终端或 CI 中记忆与检索 |
---
## 🎯 Use Cases
每个用例都遵循同一循环：将源文件放入文件夹，用 `memorize_workspace()` 同步，再用 `retrieve_workspace()` 查询。同步是增量的（仅重新处理已变更文件），顶层目录决定处理方式 — ``chat/`` → memory topics，``agent/`` → skills，其余一切 → 编入索引的上下文。
### 1. **Personal Memory**
*将聊天记录转化为用户偏好、目标、事件、决策和关系上下文。*
```python
# workspace/chat/*.json — conversation logs become memory topic files
await service.memorize_workspace(folder="./workspace")
context = await service.retrieve_workspace("What should I remember about this user?")
```
### 2. **Workspace Context for Coding Agents**
*将文档、PR 备注、日志和设计决策转化为可复用的项目记忆。*
```python
# docs, notes, and logs anywhere in the folder are captioned and indexed
await service.memorize_workspace(folder="./workspace")
context = await service.retrieve_workspace("How should I structure this module?")
```
### 3. **Multimodal Knowledge Layer**
*从文档、截图、图片、视频和音频笔记中提取可搜索的事实。*
```python
# modality is inferred per file: .pdf/.docx/.pptx/.xlsx/.html (via MarkItDown —
# pip install 'memu-py[document]'), .png/.jpg, .mp3/.wav, .mp4/.mov, ...
await service.memorize_workspace(folder="./workspace")
context = await service.retrieve_workspace("What matters for the next research plan?")
```
### 4. **Tool and Agent Learning**
*将执行轨迹转化为 skills，告知未来的 agent 哪些做法有效、哪些应当避免。*
```python
# workspace/agent/*.txt — execution traces are distilled into skill files
await service.memorize_workspace(folder="./workspace")
context = await service.retrieve_workspace("Which tools worked for config editing?")
```
---
## 🗂️ Architecture
编译后的工作区可从两个方向理解：
- `memorize_workspace()` 将文件夹写入持久的 memory 文件、skill 文件、resource 记录、segments、links 和 embeddings。
- `retrieve_workspace()` 直接读取这些层，优先对 segments 排序，再将结果汇总至 agent 应加载的文件与 resources。
记忆以三种表示层存储：
| Layer | What it holds | Retrieval Role |
|-------|---------------|----------------|
| **File**（`RecallFile`） | 合成的 memory topic 或 skill 文档 | 返回给 agent 的单位 — 命中的 segments 汇总至其所属 file |
| **Segment** | 文件的细粒度切片（段落行、skill 描述） | 嵌入搜索单位 — 查询优先对 segments 排序 |
| **Resource** | 带来源说明的原始源工件 | 当合成摘要不足时，召回原始上下文 |
`retrieve_workspace()` 将查询嵌入一次，按相似度对片段与资源排序，并返回紧凑上下文，全程零次对话 LLM（chat-LLM）调用。
运行时视角请参阅 [docs/architecture.md](docs/architecture.md)（了解 `MemoryService`、工作流流水线、存储后端与 LLM 路由），分层设计背后的决策记录请参阅 [docs/adr/](docs/adr/README.md)。
---
## 🧰 Agent Skills
本仓库内置一个 [Agent Skill](https://docs.claude.com/en/docs/agents-and-tools/agent-skills) — [`.claude/skills/memu/SKILL.md`](.claude/skills/memu/SKILL.md) — 为 Claude Code（及任何兼容 Skills 的 agent）提供工作区配对能力。agent 自行决定何时使用各方向：
- **memorize**（`memu memorize-workspace`）—「记住这个」「把这个文件夹同步到记忆」「完成值得持久化的工作」
- **retrieve**（`memu retrieve-workspace`）—「我们对……了解什么」「开始一项可能有既有上下文的任务」
在本仓库内开箱即用。若要在自己的项目中使用，将 skill 文件夹复制到该项目的 `.claude/skills/`（或 `~/.claude/skills/` 以全局启用）：
```bash
cp -r .claude/skills/memu /path/to/your-project/.claude/skills/
```
该 skill 会自动定位 CLI（`memu`、`uvx --from memu-py memu` 或 `npx memu-cli`），并将状态保存在项目本地的 `./data/memu.sqlite3` 中，因此一个会话中记忆的内容可在下一个会话中检索。对于 LangGraph agent，请参阅 [LangGraph integration](docs/langgraph_integration.md)。
---
## 🚀 Quick Start
### Option 1: Cloud Version
👉 **[memu.so](https://memu.so)** — 托管式 API，提供托管摄取、结构化记忆与检索
企业部署请联系：**info@nevamind.ai**
#### Cloud API (v3)
| Base URL | `https://api.memu.so` |
|----------|----------------------|
| Auth | `Authorization: Bearer 
```python
result = await service.memorize_workspace(
folder="./workspace", # scanned recursively; modality inferred per file
user={"user_id": "123"}, # optional scope
)
# Returns the diff plus what changed:
# { "added": [...], "modified": [...], "deleted": [...],
# "resources": [...], "entries": [...], "files": [...] }
```
- 将文件夹与旁路 `.memu_manifest.json` 进行 diff — 仅处理新增/修改的文件，已删除文件对应的记忆会级联移除
- 按顶层目录路由：`chat/` → 记忆文件，`agent/` → skill 文件，其余 → 已索引的工作区上下文
- 当 `memory_files_config.enabled=True` 时重建 markdown 记忆树（`INDEX.md` / `MEMORY.md` / `SKILL.md`）
---
### `retrieve_workspace()` — Fast, LLM-Free Retrieval
```python
result = await service.retrieve_workspace(
"deploy checklist",
where={"user_id": "123"},
)
# Returns:
# { "segments": [...], # embedded slices ranked by similarity
# "files": [...], # the memory/skill files those segments roll up to
# "resources": [...] } # workspace resources ranked by similarity
```
查询仅嵌入一次，按向量相似度排序 — 无意图路由、无查询改写、无充分性检查、零次 LLM 调用。适用于高频查询场景，此时延迟与成本比深度推理更重要。
---
## 💡 Example Workflows
### Always-Learning Assistant
```bash
export OPENAI_API_KEY=your_key
uv run python examples/example_1_conversation_memory.py
```
自动提取偏好、构建关系模型，并在后续对话中呈现相关上下文。
### Self-Improving Agent
```bash
uv run python examples/example_2_skill_extraction.py
```
监控 agent 行为，识别成功与失败中的模式，并从经验中自动生成 skill 指南。
### Multimodal Context Builder
```bash
uv run python examples/example_3_multimodal_memory.py
```
自动将文本、图像与文档交叉引用，汇入统一的记忆层。
---
## 📊 Performance
memU 在所有推理任务上的 Locomo 基准测试中达到 **92.09% 平均准确率**。
