Agent Memory1.0 Skill

agent-memory1.0_skill

触发条件

需要召回或写入用户历史处理记忆时调用。本 Skill 直接调用 agent-memory1.0 容器的 HTTP API（端口 8517）， 不依赖 MemoryRail 框架。内置熔断器、批量写入缓冲、fail-open 降级等完整功能。

call_mcp 参数

召回记忆

{
  "script_command": "python agent-memory1.0_skill/scripts/run_memory_operation.py",
  "script_params": "{\"operation\": \"search\", \"user_id\": \"{user_id}\", \"query\": \"用户 {user_id} 的历史处理记录\", \"top_k\": 5}"
}

写入记忆

{
  "script_command": "python agent-memory1.0_skill/scripts/run_memory_operation.py",
  "script_params": "{\"operation\": \"save\", \"user_id\": \"{user_id}\", \"content\": \"处理结果...\", \"role\": \"assistant\"}"
}

缓冲写入（批量积累后统一刷新）

{
  "script_command": "python agent-memory1.0_skill/scripts/run_memory_operation.py",
  "script_params": "{\"operation\": \"save\", \"user_id\": \"{user_id}\", \"content\": \"中间结果...\", \"buffer\": true}"
}

刷新缓冲区

{
  "script_command": "python agent-memory1.0_skill/scripts/run_memory_operation.py",
  "script_params": "{\"operation\": \"flush\", \"user_id\": \"{user_id}\"}"
}

查看状态

{
  "script_command": "python agent-memory1.0_skill/scripts/run_memory_operation.py",
  "script_params": "{\"operation\": \"status\"}"
}

更新记忆

{
  "script_command": "python agent-memory1.0_skill/scripts/run_memory_operation.py",
  "script_params": "{\"operation\": \"update\", \"user_id\": \"{user_id}\", \"mem_id\": \"{mem_id}\", \"memory\": \"修正后的内容...\"}"
}

删除单条记忆

{
  "script_command": "python agent-memory1.0_skill/scripts/run_memory_operation.py",
  "script_params": "{\"operation\": \"delete\", \"user_id\": \"{user_id}\", \"mem_id\": \"{mem_id}\"}"
}

批量删除记忆

{
  "script_command": "python agent-memory1.0_skill/scripts/run_memory_operation.py",
  "script_params": "{\"operation\": \"batch_delete\", \"user_id\": \"{user_id}\", \"mem_ids\": [\"mem_abc\", \"mem_def\"]}"
}

更新画像变量

{
  "script_command": "python agent-memory1.0_skill/scripts/run_memory_operation.py",
  "script_params": "{\"operation\": \"update_variables\", \"user_id\": \"{user_id}\", \"variables\": {\"status\": \"normal\", \"priority\": \"high\"}}"
}

删除画像变量

{
  "script_command": "python agent-memory1.0_skill/scripts/run_memory_operation.py",
  "script_params": "{\"operation\": \"delete_variables\", \"user_id\": \"{user_id}\", \"names\": [\"old_var_name\"]}"
}

消息溯源

{
  "script_command": "python agent-memory1.0_skill/scripts/run_memory_operation.py",
  "script_params": "{\"operation\": \"trace\", \"message_id\": \"{message_id}\"}"
}

参数说明

通用参数

search 操作

get 操作

save 操作

flush 操作

status 操作

无需参数。

update 操作

delete 操作

batch_delete 操作

update_variables 操作

delete_variables 操作

trace 操作

返回字段

search 操作

{
  "success": true,
  "operation": "search",
  "user_id": "<YOUR_USER_ID>",
  "scope_id": "edp_agent",
  "total_results": 3,
  "variables": {"category": "general", "priority": "normal"},
  "results": [
    {
      "content": "2024-01-15，用户 USER_001 处理结论：正常...",
      "type": "summary",
      "score": 1.0,
      "source": "summary_search"
    }
  ],
  "search_summary": "共召回 3 条记忆：画像变量 2 项 + 向量搜索 0 条 + 摘要搜索 1 条 + 页面检索 2 条",
  "breaker_open": false
}

save 操作（直接写入）

{
  "success": true,
  "operation": "save",
  "user_id": "<YOUR_USER_ID>",
  "mode": "direct",
  "message_count": 1,
  "breaker_open": false
}

save 操作（缓冲写入）

{
  "success": true,
  "operation": "save",
  "user_id": "<YOUR_USER_ID>",
  "mode": "buffered",
  "buffered_messages": 1,
  "buffer_total_chars": 1523,
  "buffer_threshold": 20000,
  "breaker_open": false
}

save 操作 — 空内容时

{
  "success": false,
  "operation": "save",
  "user_id": "<YOUR_USER_ID>",
  "error": "没有可写入的消息内容（全部为空或仅包含空白字符）",
  "mode": "filtered",
  "breaker_open": false
}

v1.1+ 修复：当所有消息的 content 均为空字符串或仅包含空白字符时：

• Skill 本地过滤（防御层）→ 返回 success: false（如上）
• 若绕过 skill 直接调用 mem1.0 HTTP API → mem1.0 返回 HTTP 422 {"detail": "No valid messages (all content is empty)"}

PR #244 已修复：mem1.0 服务端现在过滤空内容和纯空白内容（content.strip() == ""）。Skill 仍保留本地过滤作为熔断/buffer 场景的防御层。

flush 操作

{
  "success": true,
  "operation": "flush",
  "user_id": "<YOUR_USER_ID>",
  "flushed_count": 5,
  "breaker_open": false
}

status 操作

{
  "success": true,
  "operation": "status",
  "circuit_breaker": {
    "open": false,
    "failure_count": 0,
    "threshold": 5,
    "cooldown_seconds": 120,
    "breaker_open_until": 0.0
  },
  "config": {
    "base_url": "<YOUR_MEMORY_BASE_URL>",
    "timeout": 30,
    "buffer_chars_threshold": 20000,
    "state_dir": "/tmp/mem1_skill_state"
  },
  "buffers": {}
}

update 操作

{
  "success": true,
  "operation": "update",
  "user_id": "<YOUR_USER_ID>",
  "scope_id": "edp_agent",
  "mem_id": "mem_abc123",
  "message": "Memory updated successfully",
  "breaker_open": false
}

delete 操作

{
  "success": true,
  "operation": "delete",
  "user_id": "<YOUR_USER_ID>",
  "scope_id": "edp_agent",
  "mem_id": "mem_abc123",
  "message": "Memory deleted successfully",
  "breaker_open": false
}

batch_delete 操作

{
  "success": true,
  "operation": "batch_delete",
  "user_id": "<YOUR_USER_ID>",
  "scope_id": "edp_agent",
  "deleted": 2,
  "failed": 0,
  "errors": [],
  "breaker_open": false
}

update_variables 操作

{
  "success": true,
  "operation": "update_variables",
  "user_id": "<YOUR_USER_ID>",
  "scope_id": "edp_agent",
  "updated_count": 2,
  "message": "Variables updated successfully",
  "breaker_open": false
}

delete_variables 操作

{
  "success": true,
  "operation": "delete_variables",
  "user_id": "<YOUR_USER_ID>",
  "scope_id": "edp_agent",
  "deleted": 1,
  "breaker_open": false
}

trace 操作

{
  "success": true,
  "operation": "trace",
  "message_id": "msg_abc123",
  "message": {
    "role": "user",
    "content": "原始对话内容...",
    "timestamp": "2026-08-26T15:36:17.517757+08:00"
  },
  "breaker_open": false
}

时区说明：v1.1+（对应 mem1.0 PR #244 后），timestamp 字段使用本地时区（带时区偏移，如 +08:00），不再强制使用 UTC。Agent 在解析时间戳时应考虑时区信息。

trace 操作 — 消息不存在时

{
  "success": true,
  "operation": "trace",
  "message_id": "msg_nonexistent_id",
  "message": {
    "found": false,
    "message_id": "msg_nonexistent_id"
  },
  "breaker_open": false
}

v1.1+ 修复：当 message_id 不存在时，mem1.0 不再返回 HTTP 500，而是 {"found": false}（PR #244 已修复 message_manager.get_by_id 的 BaseError 异常处理）。Skill 仍返回 success: true，调用方需检查 message.found 字段判断溯源是否成功。

失败时（fail-open）

{
  "success": false,
  "operation": "search",
  "user_id": "<YOUR_USER_ID>",
  "error": "连接失败: Connection refused",
  "results": [],
  "breaker_open": false
}

环境变量

召回链路

search 操作（与 MemoryRail _http_search_mem1 完全对等）:
  0. POST /get_variables/              ← 用户画像变量（risk_preference 等）
  1. POST /search_memory/              ← 向量语义搜索
     ↓
  2. POST /search_user_history_summary/ ← 对话摘要搜索
     ↓ 无结果或结果不足
  3. POST /get_user_mem_by_page/       ← 页面检索（兜底，仅在前 3 路返回空时触发）
     ↓
  合并去重 → 返回 results + variables

写入链路

save 操作 (buffer=false):
  POST /add_messages/  →  直接写入 agent-memory1.0

save 操作 (buffer=true):
  追加到缓冲区文件  →  满足阈值时自动 flush
                    →  或手动调用 flush 操作

更新与删除链路

update 操作:
  POST /update_mem_by_id/  →  用新内容替换指定记忆

delete 操作:
  POST /delete_mem_by_id/  →  删除单条记忆

batch_delete 操作:
  POST /batch_delete_mem/  →  批量删除多条记忆（向量 + KV 批量删，非逐条 HTTP）

update_variables 操作:
  POST /update_variables/  →  创建或更新用户画像变量

delete_variables 操作:
  POST /delete_variables/  →  按名称删除用户画像变量

消息溯源链路

trace 操作:
  POST /get_message_by_id/  →  返回原始消息的 role / content / timestamp
  用途：从记忆的 source_id 追溯到原始对话，满足审计要求

熔断器 (Circuit Breaker)

正常状态:  failure_count = 0, breaker_open = false
  ↓
第1次失败: failure_count = 1
第2次失败: failure_count = 2
...
第5次失败: failure_count = 5 → 熔断器打开! 冷却 120 秒
  ↓
冷却期间: 所有操作直接返回 success:false，不发起 HTTP 请求
  ↓
120 秒后:  自动复位，尝试下一次调用
  ├─ 成功 → failure_count 归零，恢复正常
  └─ 失败 → 重新开始计数...

• 熔断器状态存储在 {MEM1_STATE_DIR}/circuit_breaker.json，跨进程共享
• 召回和写入共享同一个熔断器
• 冷却时间到后自动复位，无需人工干预

批量写入 (Batch Write)

save (buffer=true) → 追加到 {MEM1_STATE_DIR}/buffer_{user_id}.jsonl
                   → 累计字符数 >= MEM1_BUFFER_CHARS_THRESHOLD (20000) → 自动 flush
flush 操作         → 手动将缓冲区所有消息批量写入 agent-memory1.0

三种触发条件：

1. 字符数阈值（主力）：缓冲区累计字符数 ≥ MEM1_BUFFER_CHARS_THRESHOLD
2. 手动 flush：AgentRule.md 调用 flush 操作
3. 自动 flush：下次 save 时检测到超过阈值，先 flush 再追加

fail-open（故障降级）

所有操作出现错误时：

• 返回 success: false + 结构化错误信息
• 不抛异常，不中断 Agent 流程
• 熔断器打开时跳过 HTTP 调用，直接返回降级结果
• 消息内容自动截断（超过 3900 字符）

注意事项

1. 召回链路与 MemoryRail 完全对等：四路召回（get_variables → search_memory → search_user_history_summary → get_user_mem_by_page 兜底），确保 Skill 方式与代码修改方式获得相同质量的记忆数据
2. user_id 隔离：agent-memory1.0 按 user_id + scope_id 隔离数据，确保不同用户数据不交叉
3. 不依赖 EDPAgent 框架：本 Skill 是纯 Python HTTP 脚本，不依赖 risk_review.skill_runtime 等内部模块，可以独立运行和测试
4. 熔断器跨进程共享：通过文件系统实现，确保多次 call_mcp 调用之间熔断器状态一致
5. 缓冲写入适用于多轮对话：AgentRule.md 中每轮调用 save 时使用 buffer: true，对话结束时调用 flush 统一写入
6. scope_id 默认值：edp_agent，与 MemoryRail 的 memory_scope_id 保持一致

附：mem1.0 服务端其他端点（运维参考，未集成到 Skill）

以下端点由 mem1.0 服务端提供，但未被本 Skill 集成（运维场景使用，Agent 无需调用）：

设计原则：Skill 仅集成 Agent 必需的操作，运维/管理类端点通过独立脚本或平台工具直接调用。

附：v1.1 变更摘要（对应 mem1.0 PR #244）

Skill 代码无需修改即可兼容 PR #244 后的 mem1.0 服务端。