Cyrene/docs/api/backend-services/memory-service.md

Memory-Service API

Base URL: http://<host>:8094 | Auth: 无（按 user_id 隔离数据）

记忆服务负责长期记忆的存储、检索、合并、衰减以及后台思考日志记录。

---

目录

1. 数据模型
2. POST /api/v1/memories — 创建记忆
3. GET /api/v1/memories — 记忆列表
4. GET /api/v1/memories/:id — 获取记忆
5. PUT /api/v1/memories/:id — 更新记忆
6. DELETE /api/v1/memories/:id — 删除记忆
7. POST /api/v1/memories/query — 搜索记忆
8. POST /api/v1/memories/consolidate — 合并记忆
9. POST /api/v1/memories/decay — 记忆衰减
10. GET /api/v1/memories/categories — 分类统计
11. POST /api/v1/thinking — 记录思考
12. GET /api/v1/thinking — 思考列表
13. GET /api/v1/thinking/:id — 思考详情
14. GET /api/v1/thinking/stats — 思考统计
15. GET /api/v1/health — 健康检查

---

数据模型

MemoryEntry

JSON 字段	Go 类型	说明
id	string	UUID 主键
user_id	string	所属用户 (max 64 chars)
content	string	完整记忆文本
summary	string	简短摘要
category	string	7 种: user_preference, personal_info, conversation, knowledge, event, task, relationship
priority	int	0=Temp, 1=Normal, 2=Important, 3=Core (写入时 clamp [0,10])
importance	int	1-10 (默认 5)
keywords	[]string	关键词标签
session_id	string	来源会话 ID
source	string	conversation, manual, merged, consolidated
access_count	int	访问次数
last_access	string	最近访问时间 (RFC3339)
created_at	string	创建时间
updated_at	string	更新时间
expires_at	string/null	临时记忆过期时间 (omitempty)

ThinkingLog

JSON 字段	Go 类型	说明
id	string	UUID
user_id	string	所属用户
content	string	思考日志全文
tool_calls	string	JSON 数组 (字符串存储)
tool_call_count	int	工具调用次数
content_length	int	内容字符长度
created_at	string	创建时间 (RFC3339)

ThinkingStats

JSON 字段	Go 类型	说明
total_logs	int	思考日志总数
total_tool_calls	int	工具调用总次数
avg_content_length	float64	平均内容长度
latest_at	string	最近日志时间

---

1. POST /api/v1/memories — 创建记忆

创建时自动去重：与已有记忆的 Jaccard/双字母组相似度 >= 0.75 时，合并内容到已有条目而非新建。

// 请求
{
  "user_id": "string (必填)",
  "content": "string (必填)",
  "summary": "string",
  "category": "string (默认 knowledge, 七选一)",
  "priority": 1,
  "importance": 5,
  "keywords": ["tag1", "tag2"],
  "session_id": "string",
  "source": "string (默认 manual)"
}

// 响应 201
{ "status": "saved", "memory": MemoryEntry }

错误

状态码	错误
400	缺少 user_id 或 content
400	请求格式错误: ...
405	method not allowed
500	数据库错误

---

2. GET /api/v1/memories — 记忆列表

Query 参数

参数	必填	默认	说明
user_id	是	—	用户 ID
category	否	全部	分类过滤
min_importance	否	0	最低重要度
limit	否	50	最大条数

响应 200

{ "user_id": "string", "memories": [ MemoryEntry, ... ], "total": 10 }

---

3. GET /api/v1/memories/:id — 获取记忆

访问后异步递增 access_count。

// 响应 200
{ "memory": MemoryEntry }

// 错误 404
{ "error": "记忆不存在" }

---

4. PUT /api/v1/memories/:id — 更新记忆

Body 所有字段可选 (partial update)。user_id 和 session_id 不可修改。

// 请求
{
  "content": "新内容",
  "summary": "新摘要",
  "category": "knowledge",
  "priority": 2,
  "importance": 8,
  "keywords": ["新标签"],
  "source": "manual"
}

// 响应 200
{ "status": "updated", "memory_id": "uuid" }

---

5. DELETE /api/v1/memories/:id — 删除记忆

不检查存在性，始终返回成功。

{ "status": "deleted", "memory_id": "uuid" }

---

6. POST /api/v1/memories/query — 搜索记忆

内部使用 SQL ILIKE + 应用层子串匹配在 content/summary/keywords 中搜索，按 importance 降序排序并去重。

// 请求
{
  "user_id": "string (必填)",
  "query_text": "关键词",
  "category": "knowledge",
  "min_importance": 3,
  "limit": 10
}

// 响应 200
{ "user_id": "string", "query": "关键词", "memories": [ MemoryEntry ], "total": 3 }

---

7. POST /api/v1/memories/consolidate — 合并记忆

查找 Jaccard 相似度 >= 0.75 的记忆对，合并关键词、增加 importance、删除重复条目。

// 请求
{ "user_id": "string (必填)" }

// 响应 200
{ "status": "consolidated", "user_id": "string", "merged": 3, "message": "记忆整理完成" }

---

8. POST /api/v1/memories/decay — 记忆衰减

两阶段操作：

1. 降级: access_count < 3、最近 30 天未访问、importance < 3、priority > 0、非 personal_info/user_preference → priority -1
2. 删除: priority = 0、access_count = 0、最近 14 天未访问

// 请求
{ "user_id": "string (必填)" }

// 响应 200
{ "status": "decayed", "user_id": "string", "decayed": 5, "deleted": 2, "message": "记忆衰减完成" }

---

9. GET /api/v1/memories/categories — 分类统计

?user_id=xxx

// 响应 200
{
  "user_id": "string",
  "categories": {
    "knowledge": 12,
    "user_preference": 3,
    "conversation": 8
  }
}

---

10. POST /api/v1/thinking — 记录思考

// 请求
{
  "user_id": "string (默认 admin)",
  "content": "string (必填)",
  "tool_calls": "string (默认 [])",
  "tool_call_count": 0,
  "content_length": 0
}

// 响应 201
{ "status": "saved", "thinking": ThinkingLog }

---

11. GET /api/v1/thinking — 思考列表

?user_id=xxx&limit=20&offset=0

// 响应 200
{ "logs": [ ThinkingLog ], "total": 5 }

---

12. GET /api/v1/thinking/:id — 思考详情

// 响应 200
{ "thinking": ThinkingLog }

// 错误 404
{ "error": "思考日志不存在" }

---

13. GET /api/v1/thinking/stats — 思考统计

?user_id=xxx (可选，缺省返回全部用户)

// 响应 200
{ "total_logs": 100, "total_tool_calls": 250, "avg_content_length": 512.3, "latest_at": "2024-01-01T12:00:00Z" }

---

14. GET /api/v1/health — 健康检查

{ "status": "ok", "service": "memory-service" }
// 或数据库不可用时
{ "status": "degraded", "service": "memory-service" }