xiaowei-system/scripts/MEMORY_RECALL_SPEC.md

统一记忆入口 (memory_recall.py)

目标

提供单一 CLI 工具，同时查询织忆、TencentDB、Soulful 三套记忆系统，合并去重后输出统一上下文。

数据源

来源	端点/文件	返回字段
织忆	POST http://localhost:7821/api/v1/recall	results[].content, results[].score
TencentDB L1	POST http://localhost:8420/search/memories	results[].content, results[].priority, results[].scene
TencentDB L0	POST http://localhost:8420/search/conversations	results[].message, results[].score
Soulful 画像	~/.hermes/soulful/user-profile.json	communication_style, preferences, decisions
Soulful 牵挂	~/.hermes/soulful/cares-queue.json	cares[].content, cares[].due
Soulful 心迹	~/.hermes/soulful/heart-traces.jsonl	每次一条 JSON，每条含 timestamp, content, tags

CLI 接口

python3 memory_recall.py "query text" [--top-k 3] [--format pretty|compact]

• query: 必选，查询文本
• --top-k: 每系统返回条数，默认3
• --format pretty: 默认，分区块显示
• --format compact: 单行动态摘要

输出格式 (pretty)

## 语义记忆（织忆）
[content] (score: X.XX)

## 人格记忆（TencentDB）
[type: persona/instruction] [scene]
[content] (score: X.XX)

## 对话记忆（TencentDB L0）
[session] [timestamp]
[message content] (score: X.XX)

## 关系感知（Soulful）
### 画像
[key]: [value]

### 待关注（牵挂）
- [content] (due: YYYY-MM-DD 或 null)

### 心迹
[timestamp] [content]

错误处理

• 某系统超时/不可用 → 跳过该系统，输出 ## [系统名] 暂不可用
• 零结果 → 输出空内容，不阻塞其他系统
• 三个系统全挂 → 退出码 1，返回空

依赖

• 标准库：json, urllib.request, argparse, pathlib, datetime
• 无外部依赖（curl 不用，用 urllib）

文件位置

~/.hermes/scripts/memory_recall.py