# Memory Agents Lab

五种 Agent 记忆范式的 Web 对比实验台：在同一个 AI 编程助手场景中观察记忆的写入、检索、治理和恢复。**当前完成可验收闭环的是 Text2Mem 和 ReMe**；Mem0、Letta 和 memU 只保留未启用的真实 SDK 适配器骨架。

## 当前实现状态

| 系统 | 当前实现 | 默认状态 |
|---|---|---|
| Text2Mem | 内置教学引擎：Encode / Retrieve、记忆分类、去重、混合检索、持久化、删除与审计 | 可直接使用 |
| ReMe | `reme-ai[core]>=0.4,<0.5`：Markdown + 多查询 BM25 + 可选 Qwen/pgvector 向量召回 | 当前已启用 |
| Mem0 | `mem0ai` 试验性适配器骨架，尚未完成公共记忆面板、删除和重置闭环 | 未启用 |
| Letta | `letta-client` 试验性适配器骨架，尚未完成 Agent ID 持久化与记忆投影 | 未启用 |
| memU | `memu-py` 试验性适配器骨架，尚未完成队列、预算和候选记忆审批闭环 | 未启用 |

未配置或未安装的系统会在 Web 端显示 `unavailable` 和具体配置提示，不会用模拟代码冒充真实框架。

## 运行方式

### 1. 启动基础设施

在项目根目录执行：

```bash
docker compose up -d
```

默认服务：

- PostgreSQL + pgvector：`localhost:54329`
- Redis：`localhost:6379`

### 2. 配置环境变量

```bash
cp .env.example .env
```

至少可以先保持模型 API 为空，Text2Mem 仍可用本地证据模式运行；模型服务临时失败时也会自动退回本地证据。接入自然语言回答时填写：

```dotenv
LLM_BASE_URL=https://api.openai.com/v1
LLM_API_KEY=your-key
LLM_MODEL=gpt-4o-mini
EMBEDDING_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
EMBEDDING_API_KEY=your-dashscope-key
EMBEDDING_MODEL=text-embedding-v4
EMBEDDING_DIMENSIONS=1536
EMBEDDING_MIN_SCORE=0.35
```

接口是 OpenAI-compatible 形式，因此可以替换为 DeepSeek、通义、硅基流动、OpenRouter 或本地 Ollama 等服务。不要把真实 API Key 写入代码或提交到 Git。

`EMBEDDING_MIN_SCORE` 是项目 pgvector 召回阈值。当前 `text-embedding-v4` 测试值使用 `0.35`；更换模型后应在测试集上重新标定。

### 3. 启动 FastAPI

当前 ReMe 适配器使用 Python 3.13 环境。推荐用 `uv`：

```bash
cd backend
uv venv --python 3.13 .venv-reme
source .venv-reme/bin/activate
uv pip install -e '.[reme]'
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
```

如果本机没有 Python 3.13，先执行 `uv python install 3.13`。

后端接口文档：<http://localhost:8000/docs>

### 4. 启动 Next.js

另开终端：

```bash
cd frontend
cp .env.local.example .env.local
npm install
npm run dev
```

本机打开：<http://localhost:3000>；局域网设备打开：`http://本机局域网IP:3000`。前端会在每次请求时根据当前页面动态计算同一主机的 `:8000` 后端地址；Next.js 开发服务器也会在启动时自动读取本机网卡地址，不需要写死局域网 IP。

## 框架适配边界

### Mem0（后续项）

Mem0 当前只有试验性调用骨架，不应仅因 `add/search` 能返回就判定为完成。正式启用前还需补齐右侧记忆投影、单条删除、重置、冲突与租户隔离测试。

当前适配器使用官方 Python SDK 的 `Memory.add(..., user_id=...)` 与 `Memory.search(..., user_id=...)` 形状。

```bash
cd backend
uv pip install mem0ai
```

当前在 `.env` 中保持关闭：

```dotenv
MEM0_ENABLED=false
```

Mem0 的模型、Embedding 和向量后端请按目标版本官方文档配置；不要假设某个后端或企业功能会自动启用。只有补齐公共记忆投影、删除、重置、冲突和隔离闭环后，才可改为 `true`。

### Letta（后续项）

Letta 当前只有试验性调用骨架。后端重启后的 Agent ID 恢复、Core / Archival / Recall 投影、删除和工具权限尚未实现，因此当前保持关闭。

```bash
cd backend
uv pip install letta-client
```

另外启动目标版本的 Letta 服务端，并设置：

```dotenv
LETTA_BASE_URL=http://localhost:8283
LETTA_API_KEY=
LETTA_ENABLED=false
```

适配器使用 `client.agents.create(...)` 和 `client.agents.messages.create(...)`。如果 SDK 或服务端版本的接口发生变化，Web 端会显示调用错误，需按目标版本文档更新适配器。

### ReMe（当前启用）

当前适配器使用官方 SDK 依赖和 Python 3.13：

```bash
cd backend
source .venv-reme/bin/activate
uv pip install -e '.[reme]'
```

回到本项目后：

```dotenv
REME_ENABLED=true
```

适配器使用当前官方 `reme.reme.ReMe`，通过 `auto_memory` 写入 Markdown 文件，再通过 `reindex` 完成索引。ReMe 0.4.1.0 的 `search` 能支持向量 + BM25/RRF，但项目当前保持其内部 `embedding_store` 为空，实际使用多查询 BM25；配置 Qwen Embedding 后，再由项目的 pgvector 索引提供向量召回。两路结果去重后，模型只依据证据回答。

ReMe 只对稳定偏好、项目事实、进度变化、可复用故障经验和长期流程规则运行 `auto_memory`；普通提问只检索，不写入长期记忆。右侧面板的一项代表一个 Markdown 记忆文件，一个文件可包含多条事实；删除按钮删除的是整个文件。

为避免本地实验在无人操作时修改文件或产生模型费用，适配器关闭了 ReMe 默认文件监听、资源整理、摘要监听和 Dream 定时任务的自动调度；每次聊天仍会显式执行 `reindex`。需要扩展能力时应显式接入对应 Job，当前不会在后台主动整理或推送。

### memU（后续项）

memU 当前只有试验性调用骨架，队列、重试、预算、同意与主动触达关闭开关尚未实现，因此当前保持关闭。

memU 官方仓库当前建议从源码安装，并要求较新的 Python 版本。请根据官方仓库锁定 commit：

```bash
git clone https://github.com/NevaMind-AI/memU.git /tmp/memU
cd /tmp/memU
git rev-parse HEAD
uv pip install -e .
```

回到本项目后仍保持关闭：

```dotenv
MEMU_ENABLED=false
```

后续适配器目标是调用 `memorize()` 与 `retrieve()`，并把兴趣推断视为待审批候选记忆，不执行主动触达；当前尚未形成可验收闭环。

## 记忆治理边界

- 当前是单工作区模式，默认 `WORKSPACE_ID=local-workspace`。
- 数据模型保留 `workspace_id`，为未来登录和多租户隔离预留。
- Text2Mem 的写入带有 IR、来源、置信度、时间和审计信息。
- `/api/reset` 已对 Text2Mem 和 ReMe 完成闭环；未启用适配器不得据此假定外部框架数据也已删除。
- 主动推送默认关闭。
- 模型生成的推断不能自动伪装成用户事实。

## API

```text
GET  /api/health
GET  /api/systems
POST /api/chat
GET  /api/memories?system=text2mem
DELETE /api/memories/{memory_id}?system=text2mem
GET  /api/audit?system=text2mem
POST /api/reset
```

## 测试

```bash
cd backend
source .venv-reme/bin/activate
uv pip install "pytest>=8.3,<9" "pytest-asyncio>=0.25,<1" "ruff>=0.9,<1"
python -m pytest -q
ruff check app tests
```

前端检查：

```bash
cd frontend
npm run build
```

## 官方资料核验入口

- Mem0 Python Quickstart：<https://docs.mem0.ai/open-source/python-quickstart>
- Letta Python SDK：<https://docs.letta.com/api/python>
- ReMe 官方仓库：<https://github.com/agentscope-ai/ReMe>
- memU 官方仓库：<https://github.com/NevaMind-AI/memU>

这些项目的 API、安装方式、Python 要求和后端支持会变化。每次启用可选适配器时，都应把版本或 commit 记录到本项目的环境记录中。