MemoryAgents

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. 启动基础设施

在项目根目录执行：

docker compose up -d

默认服务：

• PostgreSQL + pgvector：localhost:54329
• Redis：localhost:6379

2. 配置环境变量

cp .env.example .env

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

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：

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

另开终端：

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=...) 形状。

cd backend
uv pip install mem0ai

当前在 .env 中保持关闭：

MEM0_ENABLED=false

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

Letta（后续项）

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

cd backend
uv pip install letta-client

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

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：

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

回到本项目后：

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：

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

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

MEMU_ENABLED=false

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

记忆治理边界

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

API

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

测试

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

前端检查：

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 记录到本项目的环境记录中。