ai-agent/MemoryAgents/使用文档.md

Memory Agents Lab 使用文档

本文档面向第一次运行本项目的使用者，说明如何启动 Web 应用、配置模型 API 和 Docker 基础设施。当前可验收的是 Text2Mem 与 ReMe；Mem0、Letta 和 memU 仅保留未启用适配器骨架。

项目目录：

/memory-agents-web/

一、项目组成

memory-agents-web/
├── backend/                 # FastAPI 后端和五种记忆适配器
├── frontend/                # Next.js Web 前端
├── infra/initdb/            # PostgreSQL 初始化脚本
├── docker-compose.yml       # PostgreSQL + pgvector + Redis
├── .env.example             # 后端和基础设施配置模板
└── 使用文档.md              # 本文档

当前项目是单工作区模式，不需要注册和登录。默认工作区标识为 local-workspace。

二、环境要求

基础运行环境：

• macOS、Linux 或 Windows + WSL；
• Docker Desktop；
• Docker Compose；
• Python 3.13（运行当前 ReMe 适配器）；
• Node.js 20+；
• npm；
• uv，推荐使用它创建 Python 虚拟环境。

只运行 Text2Mem 或基础 Web 界面时，Python 3.11 也可以；但按当前默认配置同时运行 ReMe 时，请统一使用 Python 3.13。

检查环境：

docker --version
docker compose version
python3 --version
node --version
npm --version
uv --version

三、配置文件

1. 创建后端配置文件

在项目根目录执行：

cd "/memory-agents-web"
cp .env.example .env

后端启动时会读取项目根目录下的 .env。

2. 根目录 .env 配置项

项目运行配置

APP_ENV=development
WORKSPACE_ID=local-workspace
DATA_DIR=./data
DEMO_FALLBACK=true

说明：

• WORKSPACE_ID：当前单工作区标识；不要在同一个数据库中随意改动，否则会看不到之前的记忆。
• DATA_DIR：本地文件型适配器和降级存储的数据目录。
• DEMO_FALLBACK：保留本地启动能力。真实框架没有安装时不会伪装成已接入，而是显示不可用状态。

OpenAI-compatible 模型 API

LLM_BASE_URL=https://api.openai.com/v1
LLM_API_KEY=你的模型API-Key
LLM_MODEL=gpt-4o-mini

EMBEDDING_BASE_URL=https://api.openai.com/v1
EMBEDDING_API_KEY=你的Embedding API-Key
EMBEDDING_MODEL=text-embedding-3-small
EMBEDDING_DIMENSIONS=1536
EMBEDDING_MIN_SCORE=0.35

当前 ReMe 第二阶段推荐使用通义千问 Embedding：

EMBEDDING_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
EMBEDDING_API_KEY=你的DashScope-API-Key
EMBEDDING_MODEL=text-embedding-v4
EMBEDDING_DIMENSIONS=1536
EMBEDDING_MIN_SCORE=0.35

这组配置使用 OpenAI-compatible /embeddings 接口。也可以替换为其他兼容 OpenAI API 的 Embedding 服务。EMBEDDING_MIN_SCORE 控制项目 pgvector 结果进入回答证据的最低余弦相似度；0.35 是当前 text-embedding-v4 测试起点，更换模型后应重新标定。

如果只想先体验 Text2Mem，可以暂时不填写 LLM_API_KEY。此时 Text2Mem 会使用本地模式回答，并仍然记录记忆和审计事件。

项目启动时会把 LLM_* 配置同步给部分依赖 OpenAI 环境变量命名的 SDK。如果某个 SDK 使用特殊配置方式，应以该 SDK 当前版本文档为准。

Docker 基础设施连接

DATABASE_URL=postgresql://memory:memory@localhost:54329/memory_agents
REDIS_URL=redis://localhost:6379/0

对应的 Docker 服务为：

服务	地址	用途
PostgreSQL + pgvector	localhost:54329	结构化记忆、向量扩展、审计数据
Redis	localhost:6379	缓存和异步任务基础设施

可选框架配置

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

MEM0_ENABLED=false
REME_ENABLED=true
MEMU_ENABLED=false

当前只应保持 REME_ENABLED=true。Mem0、Letta 和 memU 即使安装了 SDK，也仍应保持关闭，直到各自的持久化、删除、重置和验收闭环补齐。

3. 前端配置文件

前端使用单独的配置文件：

cd frontend
cp .env.local.example .env.local

默认保持未设置：

# NEXT_PUBLIC_API_URL=https://api.example.com

未设置时，前端会在浏览器运行时使用当前页面的协议和主机名，动态组合 :8000 后端地址。只有后端使用不同主机或端口时才设置 NEXT_PUBLIC_API_URL；不要为局域网访问写死 localhost 或某个局域网 IP。

四、启动基础设施

回到项目根目录：

cd "/memory-agents-web"
docker compose up -d

查看运行状态：

docker compose ps

正常情况下，两个服务都应显示 healthy 或 running。

检查 pgvector：

docker compose exec postgres \
  psql -U memory -d memory_agents \
  -c "SELECT extname FROM pg_extension WHERE extname = 'vector';"

停止服务但保留数据卷：

docker compose down

停止服务并删除数据库数据：

docker compose down -v

docker compose down -v 会删除本项目的 PostgreSQL 和 Redis 数据，只有在确认不需要历史记忆时使用。

五、启动 FastAPI 后端

推荐方式：Text2Mem + ReMe（Python 3.13）

cd "/memory-agents-web/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

后端地址：

• API：http://localhost:8000
• Swagger 文档：http://localhost:8000/docs
• 健康检查：http://localhost:8000/api/health

如果已经创建过 .venv-reme，后续只需要：

cd backend
source .venv-reme/bin/activate
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

精简方式：只运行 Text2Mem（Python 3.11+）

如果将 .env 中 REME_ENABLED=false，可以只安装基础依赖：

cd backend
uv venv --python 3.11 .venv
source .venv/bin/activate
uv pip install -e .
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

不要在一个已经安装大量旧版框架依赖的虚拟环境中强行混用不同 Python 版本要求。

六、启动 Next.js 前端

另开一个终端窗口：

cd "/memory-agents-web/frontend"
cp .env.local.example .env.local
npm install
npm run dev

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

前端页面包含：

• 五种记忆系统切换；
• AI 编程助手对话区；
• 当前系统状态；
• 当前记忆列表；
• 最近审计事件；
• 清空当前系统记忆按钮。

七、五种适配器状态

1. Text2Mem

Text2Mem 是本项目内置的教学型 IR 执行引擎，不需要额外安装 SDK。

在对话中发送类似内容：

记住：我偏好使用 Python + FastAPI，数据库选 PostgreSQL。

系统会记录：

• ENC/Encode 写入操作；
• 记忆内容、来源和置信度；
• RET/Retrieve 检索操作；
• 审计事件。

当前还会将陈述分为 semantic、episodic、procedural 和 task-state，对完全重复的内容去重，并使用关键词、记忆类型与可选 Embedding 进行融合检索。“上次部署遇到了什么问题？”这类问句只检索，不会被误存为新记忆。

2. Mem0（后续项）

当前只有试验性 add/search 骨架，右侧记忆投影、单条删除、重置和冲突验收尚未完成。下列命令只用于后续开发，不表示当前已可用。

安装 SDK：

cd backend
source .venv-reme/bin/activate
uv pip install mem0ai

当前在根目录 .env 中保持关闭：

MEM0_ENABLED=false

Mem0 的模型、Embedding 和向量后端会随版本变化。后续补齐闭环时请先核对官方 Python Quickstart：https://docs.mem0.ai/open-source/python-quickstart。

3. Letta（后续项）

当前尚未完成 Agent ID 持久化、Core / Archival / Recall 投影和删除闭环。下列命令只用于后续开发。

安装客户端：

cd backend
source .venv-reme/bin/activate
uv pip install letta-client

启动目标版本的 Letta 服务端，并确认服务地址。例如：

LETTA_BASE_URL=http://localhost:8283
LETTA_API_KEY=

当前保持 LETTA_ENABLED=false，不会启动或调用 Letta。

Letta 的 Python 客户端文档：https://docs.letta.com/api/python。

注意：Letta 客户端和服务端需要版本匹配。如果服务端 API 变化，Web 端会显示调用错误，不会自动降级成假数据。

4. ReMe（当前启用）

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

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

回到项目后启用：

REME_ENABLED=true

ReMe 会通过 auto_memory 将稳定偏好、项目事实、进度变化、可复用故障经验和长期流程规则写入 Markdown，再用 reindex 建立文件索引。ReMe 0.4.1.0 虽支持向量 + BM25/RRF，但本项目当前保持其内部 embedding_store 为空，实际使用查询改写、工程术语扩展和多查询 BM25；配置 Qwen Embedding 后，由项目的 pgvector 索引提供向量召回。两路结果去重后，模型只依据证据回答。官方仓库：https://github.com/agentscope-ai/ReMe。

适配器会使用文件型记忆，并将数据放在项目 DATA_DIR 对应目录下。

需要特别理解两点：

• ReMe 只对稳定偏好、项目事实、进度变化、可复用故障经验和长期流程规则运行 auto_memory；普通问句只检索。
• 右侧面板统计的是 Markdown 记忆文件数，不是原子事实数。一个文件可以合并多条对话事实；单条删除按钮实际删除整个文件并重建索引。
• ReMe 默认的后台文件监听、资源整理、摘要监听和 Dream 定时任务已关闭自动调度，避免无人操作时修改文件或产生模型成本；每次聊天仍会显式 reindex，扩展能力需另行接入对应 Job。

5. memU（后续项）

当前尚未完成后台队列、重试、预算、同意与候选记忆审批闭环。下列命令只用于后续开发。

memU 当前官方仓库要求较新的 Python 版本，建议使用 Python 3.13 虚拟环境。安装：

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

memU 官方仓库：https://github.com/NevaMind-AI/memU。

后续实现目标是只生成待审批的候选记忆，默认不向用户主动推送，也不自动执行高风险动作；这些尚不是当前可验收功能。

八、常用 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

聊天请求示例：

curl -X POST http://localhost:8000/api/chat \
  -H 'content-type: application/json' \
  -d '{
    "system": "text2mem",
    "message": "记住：项目使用 PostgreSQL 和 FastAPI"
  }'

九、测试和构建

后端：

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
python -m compileall -q app tests

前端：

cd frontend
npm run build
npm audit --omit=dev

十、常见问题

页面显示“后端尚未启动”

确认后端是否运行：

curl http://localhost:8000/api/health

如果无法访问，请先启动 FastAPI。

页面显示 postgres 之外的存储模式

这表示后端连接 PostgreSQL 失败，暂时使用了本地 JSON 降级存储。请检查：

docker compose ps
docker compose logs postgres

并确认 .env 中的 DATABASE_URL 与 Docker 端口一致。

/api/health 会在降级时附带 storage_error。如果更换了 Embedding 向量维度，现有 memory_embeddings 表与新维度不一致也会触发降级；应先迁移或在确认无需历史数据后重建数据卷。

当前只有 Text2Mem 和 ReMe 可用

当前项目只启用 Text2Mem 和 ReMe；Mem0、Letta、memU 保持关闭。查看 /api/systems 可以获得具体 setup_hint。

模型 API 没有配置

Text2Mem 仍可使用本地证据模式，但不会调用外部模型。若要让模型生成自然语言回答，请填写 LLM_API_KEY 并重启后端；模型服务临时失败时，Text2Mem 也会自动退回本地证据模式，写入和检索仍可继续。

ReMe 处理时间较长

ReMe 一轮写入会依次执行记忆提取、重建索引、可选向量同步、检索和证据回答，通常比 Text2Mem 慢。前端聊天请求允许最长 120 秒，删除和重置允许 60 秒；处理中不要重复发送同一条消息。如果超过时限，检查后端日志和模型服务延迟。

如何清空记忆

可以在 Web 页面点击“清空记忆”，也可以调用：

curl -X POST http://localhost:8000/api/reset \
  -H 'content-type: application/json' \
  -d '{"system":"text2mem"}'

如果要清空所有系统：

curl -X POST http://localhost:8000/api/reset \
  -H 'content-type: application/json' \
  -d '{}'

十一、安全提醒

• 不要把 .env、API Key、真实用户数据提交到 Git；
• 不要在公开网络直接暴露没有登录和权限控制的单工作区 Web 端；
• docker compose down -v 会删除本地数据库数据；
• 当前没有注册、登录和多租户隔离，只适合本地学习、演示和受控内网；
• 启用主动式记忆前，应先配置预算、频率限制、关闭开关和人工审批。