# Memory-Service API

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

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

---

## 目录

1. [数据模型](#数据模型)
2. [POST /api/v1/memories — 创建记忆](#1-post-apiv1memories)
3. [GET /api/v1/memories — 记忆列表](#2-get-apiv1memories)
4. [GET /api/v1/memories/:id — 获取记忆](#3-get-apiv1memoriesid)
5. [PUT /api/v1/memories/:id — 更新记忆](#4-put-apiv1memoriesid)
6. [DELETE /api/v1/memories/:id — 删除记忆](#5-delete-apiv1memoriesid)
7. [POST /api/v1/memories/query — 搜索记忆](#6-post-apiv1memoriesquery)
8. [POST /api/v1/memories/consolidate — 合并记忆](#7-post-apiv1memoriesconsolidate)
9. [POST /api/v1/memories/decay — 记忆衰减](#8-post-apiv1memoriesdecay)
10. [GET /api/v1/memories/categories — 分类统计](#9-get-apiv1memoriescategories)
11. [POST /api/v1/thinking — 记录思考](#10-post-apiv1thinking)
12. [GET /api/v1/thinking — 思考列表](#11-get-apiv1thinking)
13. [GET /api/v1/thinking/:id — 思考详情](#12-get-apiv1thinkingid)
14. [GET /api/v1/thinking/stats — 思考统计](#13-get-apiv1thinkingstats)
15. [GET /api/v1/health — 健康检查](#14-get-apiv1health)

---

## 数据模型

### 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 时，合并内容到已有条目而非新建。

```json
// 请求
{
  "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

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

---

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

访问后异步递增 `access_count`。

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

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

---

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

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

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

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

---

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

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

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

---

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

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

```json
// 请求
{
  "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、删除重复条目。

```json
// 请求
{ "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 天未访问

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

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

---

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

`?user_id=xxx`

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

---

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

```json
// 请求
{
  "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`

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

---

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

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

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

---

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

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

```json
// 响应 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 — 健康检查

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