🧠 多智能体记忆系统 — 内部运维文档

服务器: 43.156.57.141 (新加坡腾讯云)  |  域名: memory.lsz.name  |  版本: 3.0.2  |  最后更新: 2026-06-22

🏗️ 架构概览

🔐 API 认证 HMAC-SHA256

除 GET /health 和 /admin/* 外，所有 API 端点均需以下 HTTP 头：

认证流程

1. 获取 API Key 和 Secret（通过 /admin/api-keys 端点，仅限 localhost）
2. 构造请求体（JSON），取当前 Unix 时间戳
3. 计算签名：signature = HMAC-SHA256(secret, str(timestamp) + json_body)
4. 在请求头中附加三个认证字段

Python 认证示例

import time, hmac, hashlib, json, requests

API_KEY = "msk_xxx..."
SECRET = "xxx..."
BASE = "https://memory.lsz.name"

def api(method, path, body=None):
    ts = str(time.time())
    body_bytes = json.dumps(body).encode() if body else b""
    sig = hmac.new(
        SECRET.encode(), ts.encode() + body_bytes, hashlib.sha256
    ).hexdigest()
    headers = {
        "Content-Type": "application/json",
        "X-API-Key": API_KEY,
        "X-Timestamp": ts,
        "X-Signature": sig,
    }
    resp = requests.request(method, BASE + path, data=body_bytes, headers=headers)
    return resp.json()

# 使用示例
result = api("POST", "/memories/personal/search", {
    "agent_id": "yihui",
    "query": "策略回测",
    "limit": 5
})

👥 多团队隔离

所有记忆数据通过 team_id 字段实现硬隔离。查询时强制 WHERE team_id = ?。每个团队的 API Key 绑定固定的 team_id，跨团队数据完全不可见。

当前团队

📋 记忆类型

📡 API 端点

公开端点（无需认证）

团队管理

Agent 管理

个人记忆

工作记忆

团队记忆

生命周期管理

统计

Admin 端点 仅 localhost

⚡ 性能指标（2026-06-08 验证）

🗄️ 数据库表结构

🔧 运维操作

服务管理

# 查看服务状态
sudo systemctl status memory-system

# 重启服务
sudo systemctl restart memory-system

# 查看日志
sudo journalctl -u memory-system -f --no-pager -n 100

# Nginx 配置测试
sudo nginx -t

# 重载 Nginx
sudo systemctl reload nginx

项目路径

/opt/memory-system/              # 项目根目录
/opt/memory-system/venv/         # Python 虚拟环境
/opt/memory-system/config.py     # 配置文件
/opt/memory-system/app.py        # Flask 入口 + JSON 序列化
/opt/memory-system/api/routes.py # API 路由
/opt/memory-system/auth/api_auth.py  # HMAC 认证中间件
/opt/memory-system/storage/      # MySQL + Redis + 向量检索
/opt/memory-system/lifecycle/    # 记忆生命周期管理
/opt/memory-system/tests/        # 测试
/opt/memory-system/docs/         # 公网文档

关键配置

# config.py
MYSQL_HOST = "127.0.0.1"
MYSQL_PORT = 3306
MYSQL_USER = "your_db_user"
MYSQL_DATABASE = "memory_system"
MYSQL_UNIX_SOCKET = "/var/run/mysqld/mysqld.sock"
REDIS_HOST = "127.0.0.1"
REDIS_PORT = 6379
EMBEDDING_SERVICE_URL = "http://127.0.0.1:8080"
EMBEDDING_DIM = 512
API_PORT = 8081
WORKING_MEMORY_TTL = 86400  # 24小时

创建新 API Key（SSH 到服务器）

# 通过 localhost 访问 admin 端点
curl -X POST http://127.0.0.1:8081/admin/api-keys \
  -H 'Content-Type: application/json' \
  -d '{"team_id": "your_team_id", "name": "Your Key Name"}'

# 响应中会包含 api_key 和 secret（仅显示一次）

SSL 证书

# 自动续期已配置，手动测试:
sudo certbot renew --dry-run

# 证书路径:
/etc/letsencrypt/live/memory.lsz.name/fullchain.pem
/etc/letsencrypt/live/memory.lsz.name/privkey.pem

🔒 安全说明

• Redis 已禁用 FLUSHALL/FLUSHDB/DEBUG/SHUTDOWN 命令
• Redis CONFIG/KEYS 命令已重命名（CONFIG_b9f7e2d4, KEYS_a3c8f1e6）
• MySQL 使用 unix socket 连接
• Nginx 强制 HTTPS (Let's Encrypt)
• API 仅监听 127.0.0.1，通过 Nginx 暴露公网
• Admin 端点仅限 localhost 访问
• API 使用 HMAC-SHA256 签名认证，时间戳窗口 5 分钟

🧪 测试验证

# 运行测试
cd /opt/memory-system
./venv/bin/python tests/test_memory.py
测试覆盖: 创建团队/Agent → 写入记忆 → 语义检索 → 跨团队隔离 → 工作记忆 → 性能基准


✅ 2026-06-08 验证结果：

14/14 项测试全部通过，包括：

• 健康检查 · 统计端点 · 团队信息查询

• 个人记忆语义检索 · 团队记忆语义检索

• 写入+搜索+更新+删除全流程

• 跨团队隔离验证（wangcheng 看不到 hermes1 数据）

• 工作记忆 CRUD · 认证拒绝测试



📋 变更日志

v3.0.2 (2026-06-22) — 性能优化

核心修复：禁用 DeepSeek thinking mode

根因：DeepSeek v4-flash 默认开启思考模式，每次 LLM 调用输出 3000-7500 字符中文推理链，token 预算被吃光

修复：llm_client.py 新增 thinking 参数透传；llm_parse.py 所有 JSON 生成任务添加 thinking={"type": "disabled"}

实测提速：aggregate-scenes 7.9x, generate-persona 4.9x, extract-facts 2.0s


v3.0.1-bugfix (2026-06-22) — Bug 修复

• BGE 长文本双保险截断（服务端 512 tokens + 客户端 2000 字符）

• 空 query fallback 到 get_recent

• embedding 失败返回友好错误，不暴露内部 URL

• GET /memories/personal/{id} 405 → 补上 GET 路由

• aggregate-scenes JSON 解析失败 → thinking mode 禁用


v3.0.0 (2026-06-08) — 生命周期管理

• Pipeline 自动化引擎（自动压缩、清理、暖机）

• 原子事实提取（/lifecycle/extract-facts）

• 场景聚合（/lifecycle/aggregate-scenes）

• 用户画像生成（/lifecycle/generate-persona）