Agent Memory Leaderboard（文本记忆榜）参赛系统，基于 Mem0 OSS v2.0.17 扩展。 系统只负责两个核心能力：Add（写入历史对话记忆）与 Search（检索记忆证据）， 不生成最终答案（Answer 由主办方统一模型完成）。
GitHub：https://github.com/CodeWater517/Mem517
比赛现行协议：https://agentmemoryleaderboard.ai/rules。仓库已按 2026-08-06 官网说明和
官方公开评测仓库逐项复核，合规矩阵见 docs/OFFICIAL_COMPLIANCE.md。
本仓库是 AML 文本记忆榜的第一阶段实现：在 Mem0 开源基线之上，复现并加固 记忆写入与检索的完整工程链路——幂等、崩溃恢复、并发控制、用户隔离、 日志脱敏、PostgreSQL FTS 补充召回与全套测试体系。
文本记忆榜 + 代码提交 + 基于 Mem0 OSS 扩展改进（固定上游版本，独立 Adapter 层， 不改动 site-packages）。
见 docs/ARCHITECTURE.md。核心链路：
- Add：payload_hash 幂等 → 会话/请求 advisory lock → 原始消息原样落库 → Mem0 add → 状态机 completed / retryable_failed；
- Search：强制 user 隔离 → Mem0 语义检索（pgvector HNSW/Cosine）+ PostgreSQL FTS 原文召回 → 2:1 交织去重 → 推断题条件式证据重排 → 脱敏审计。
| 项 | 值 |
|---|---|
| Python 包 | mem0ai==2.0.17 |
| 上游 Tag | v2.0.17（commit 12c47f52） |
| 集成方式 | 固定依赖 + 独立 Adapter 层；基线无补丁（见 UPSTREAM.md、patches/） |
| 组件 | 版本 |
|---|---|
| Python | ≥3.11（冻结目标 3.11，实测 3.13 通过） |
| Mem0 | mem0ai==2.0.17 |
| 数据库 | PostgreSQL 16 + pgvector 0.8.5（HNSW / Cosine） |
| 关键词检索 | PostgreSQL Full-Text Search（tsvector + GIN + ts_rank_cd） |
| LLM / Embedding | gpt-4o-mini（temperature=0）/ text-embedding-3-small（1536 维） |
| ORM / 迁移 | SQLAlchemy 2（asyncio）+ Alembic |
| Web 框架 | FastAPI 0.115.12 + Uvicorn 0.34.2（单 worker） |
Dockerfile 按方案 §10 把 PostgreSQL 16 + pgvector 0.8.5、Python 3.11、
FastAPI、Alembic、supervisord 与 tini 打进一个镜像；只暴露 8000/tcp，PostgreSQL
只监听容器内 127.0.0.1:5432。API 以非 root 用户运行，PG 与 Mem0 history 使用
独立命名卷。
2026-08-06 已在 Docker Desktop 29.6.2（Linux/aarch64）完成无缓存构建、首次/重复
启动、Health、HTTP smoke、32 并发压测、命名卷持久化、端口和 SIGTERM 实机闸门；
两个基础镜像均已固定 SHA256 digest。实测证据见 docs/BASELINE_RESULTS.md §9。
完整清单见 .env.example，关键项：
| 变量 | 说明 |
|---|---|
AUTH_SCHEME / API_KEY |
bearer、token、x-api-key 或 none；正式评测使用前三者之一 |
LLM_API_BASE / LLM_API_KEY / LLM_MODEL |
主办方 OpenAI 兼容接口 |
EMBEDDING_* |
Embedding 配置（为空回落 LLM 配置） |
POSTGRES_* |
数据库连接 |
SEARCH_FTS_ENABLED |
FTS 补充召回开关（默认 true，§30） |
SEARCH_VERBATIM_FIRST_ENABLED |
时间查询优先展示带源时间的逐字原文（默认 true） |
SEARCH_INFERENCE_RERANK_ENABLED |
仅对推断题启用证据重排（默认 true） |
SEARCH_INFERENCE_RERANK_TOP_N |
推断题最多保留的证据数（默认 40） |
MODEL_CONCURRENCY |
模型调用全局信号量（默认 12，§31） |
make install # uv sync --locked --extra dev（锁文件复现，禁止浮动依赖）
make docker-build # Docker 可用时无缓存构建单容器镜像本地开发（需先启动 PG 并执行迁移）：
alembic upgrade head
uvicorn app.main:app --host 0.0.0.0 --port 8000 --workers 1 --proxy-headers单容器启动：
make docker-build
make docker-run
make wait-health
make smoke # 只经 HTTP 验证 Add→幂等→立即 Search→隔离完整契约见 docs/API.md。最小示例：
curl -fsS http://127.0.0.1:8000/health
curl -fsS http://127.0.0.1:8000/add \
-H 'Content-Type: application/json' \
-d '{"request_id":"demo:chunk00","messages":[{"role":"user","content":"我住在广州。"}],"user_id":"demo:user","session_id":"demo:session"}'
curl -fsS http://127.0.0.1:8000/search \
-H 'Content-Type: application/json' \
-d '{"query":"用户住在哪里？","user_id":"demo:user","top_k":100}'正式评测按申请时绑定的方式设置 AUTH_SCHEME=bearer|token|x-api-key 和 API_KEY；
/health 始终不鉴权。旧的 AUTH_ENABLED=true 仍兼容为 Bearer。契约测试：
make test-contract。
add_requests/raw_messages/search_requests/app_metadata四表， Alembic 迁移管理（0001 初始、0002 FTS）；- Mem0 记忆本体存 pgvector（HNSW 索引），历史库为本地 SQLite
（
MEM0_HISTORY_DB_PATH）； - 持久化实测：引擎重建后数据完整（
tests/integration/test_persistence.py）。
make test-offline # 当前 222 passed / 17 integration skipped
make test-integration # 17 项 PG 集成测试（需 AML_INTEGRATION=1 与本地 PG）
make test-security # 密钥扫描 + 日志脱敏测试
make verify # Docker 存在时继续执行容器 Health/HTTP smoke/压测2026-08-06 本轮结果：离线 222 passed, 17 skipped；真实集成 17 passed；
Provider preflight 的 Chat 与 text-embedding-3-small（1536 维）均通过。前一日的
直连 ConnectTimeout 已确认是网络路径问题，当前必须保留本机代理环境。
真实 API 只走 scripts/provider_preflight.py / scripts/smoke_test.py /
scripts/fts_language_probe.py，普通测试严禁真实 Key（§50.17）。
python -m scripts.provider_preflight：验证 LLM 对话与 embedding 维度（1536），
失败即终止，不静默降级（§9.2）。
- 模型调用全局信号量
MODEL_CONCURRENCY=12，临时错误重试 ≤2 次（指数退避+抖动）； - 并发正确性由集成测试覆盖（
tests/integration/test_concurrency.py，真实 PG）； - HTTP 压测已实跑：96/96 Add、1000/1000 Search，错误率均为 0%；详见基线 §9。
已实现并完成代码/公开集验证：Mem0 核心复现、HTTP 契约、鉴权与错误映射、启动/关闭
生命周期、幂等与崩溃恢复、用户隔离、日志脱敏、语义/FTS 交织召回、推断题条件式
证据重排、依赖锁定，以及
Docker 单容器的历史基线已通过 Health、HTTP 冒烟、并发压测、持久化和 SIGTERM；
当前检索候选正式冻结前仍需重跑完整容器 Gate。详见 docs/DEPLOYMENT.md、
docs/BASELINE_RESULTS.md 与 docs/HANDOVER.md。
仍不实现：知识图谱、通用 Cross-Encoder、全题 LLM 重排、多语言 BM25、 Neo4j/ES/Redis/Celery/Qdrant 等重型研究内容。当前重排器只做比赛合规的条件式 证据选择，不生成最终答案，失败时保留原始检索结果。
按比赛公开参数近似的 competition-contract 全量运行已完成：1,382/1,382 题， LLM Accuracy 73.66%、F1 0.4022、BLEU 0.3108；相对上一版 69.83% 提高 3.84pp，相对旧全量本地基线 58.97% 提高 14.69pp。预测耗时 584.6 秒，平均约 0.42 秒/题。
完整口径、20% 消融、分类结果、产物位置和剩余 bad case 见
docs/LOCOMO_REFINED_RESULTS.md。该结果是公开数据本地评测，不宣称为尚未发布的
官方榜单成绩。
PostgreSQL 内建分词不支持中文：中文查询 FTS 零命中时 Search 不失败，
自动退化纯语义检索并记录 warning。与中文相邻的中英文混合编号存在
双通道失效盲区。实测数据与边界见 docs/FTS_LANGUAGE_REPORT.md。
当前能力为 PostgreSQL FTS，不宣称严格 BM25（§30）。
见 UPSTREAM.md（Mem0 v2.0.17 / commit / Apache-2.0 / 集成方式 / 无上游源码改动）。
见 THIRD_PARTY_NOTICES.md。
见 docs/REPRODUCTION.md（含 Mac 上 PG16+pgvector 0.8.5 的完整安装与验收命令）。
app/ # settings / memory / storage / services / schemas / observability
migrations/ # Alembic：0001 初始四表、0002 FTS
scripts/ # preflight / smoke / LoCoMo-Refined runner / 安全与锁定工具
tests/ # fakes（离线替身）、unit、integration（17）
docs/ # API / DEPLOYMENT / ARCHITECTURE / REPRODUCTION /
# BASELINE_RESULTS / LOCOMO_REFINED_RESULTS / HANDOVER
patches/ # 基线无补丁
Makefile # install / test-* / verify / docker-* / wait-health / smoke
Apache-2.0，见 LICENSE、NOTICE。