修改历史

## 一、系统组件
1. Gateway（端口8001）：前端页面（首页/聊天/房间/记忆/设置）+ 请求整理 + 上下文注入 + 流式SSE + Tool use分发 
2. MCP记忆服务（端口8002）：记忆卡增删改查 + embedding + 语义/关键词检索 + 对话暂存
3. LLM：Claude API（OpenAI兼容格式）
4. Nginx：HTTPS入口（待配置）

## 二、架构
Gateway（端口8001）
  ↓ LLM API（anthropic原生，流式SSE）
  ↓ API预设快速切换
  ↓ 意图判断 + embedding → search_memory → 注入记忆
  ↓ Tool use → MCP服务(8002) / Gateway内置工具(web_search, fetch_url, create_todo, update_todo, delete_todo)
  ↓ 写入类工具短路（SHORT_CIRCUIT_TOOLS，省第二轮）
  ↓ 对话存储 gateway.db
  ↓ ref余弦自动判定 → 回写last_used_at
  ↓ remember → SSE推送toast
  ↓ dreaming → 异步日记
  ↓ echo → todo 催促
  ↓ 摘要注入 + 自动摘要
  ↓ 记忆管理 /memory
  ↓ 房间 /room
  ↓ 图片发送 + 文件上传

MCP记忆服务（端口8002）— 独立运行
  ↓ memory_mcp_http.py + embedding_utils.py
  ↓ memory.db
  ↓ 打分引擎（FinalScore + 阈值0.50 + MMR）
  ↓ 对话暂存

## 三、调用流程
前端 → Gateway → Claude API → 返回tool_use → Gateway拦截 → 调MCP服务(8002) → 结果回传 → 继续生成 → SSE流式输出到前端

## 四、技术栈
- 服务器：腾讯云（2核2GB内存，40G SSD） + Python环境
- 数据库：SQLite × 2（memory.db 记忆+对话暂存 + gateway.db 对话/日记/摘要）
- 前端：Gateway单文件(gateway.py)内嵌HTML模板
- 服务管理：systemd × 2（gateway / memory-mcp）

## 五、文件路径
【记忆库相关】
- 数据库：/home/ubuntu/memory_mcp/memory.db
- 核心代码：/home/ubuntu/memory_mcp/memory_mcp_http.py
- Embedding工具：/home/ubuntu/memory_mcp/embedding_utils.py
- 环境文件：/etc/memory-mcp.env
- 服务文件：/etc/systemd/system/memory-mcp.service

【Gateway相关】
- 数据库：/home/ubuntu/gateway/gateway.db
- 主程序：/home/ubuntu/gateway/gateway.py
- 配置：/home/ubuntu/gateway/config.json
- 服务文件：/etc/systemd/system/gateway.service
- 认证密码：/home/ubuntu/memory_mcp/admin.env（记忆页HTTPBasic）

## 六、Gateway 配置
- config.json：含 assistants 数组 + context_window + memory_inject_count + auto_summary_trigger + summary_inject_count
- main 助手下有 presets 数组 + active_preset（API预设快速切换）
- 每个助手独立配置（Base URL / Key / 模型 / 提示词）

## 七、MCP 工具（11个，AI 可见10个）
- AI 可见：remember / search_memory / save_dialogue / update_memory / forget_memory / recent_memories / search_dialogue / list_dialogues / delete_dialogue / list_topics
- AI 不可见：ref_update（ref_update 已从 AI 可用工具列表移除（不在 CORE_TOOLS 中），MCP 端接口保留，Gateway 后端 _writeback_refs_async 异步调用）

## 八、工具分组加载
- CORE_TOOLS（每次都发）：remember / save_dialogue
- EXTENDED_TOOLS（用户消息含关键词 或 AI上轮回复含"i need extended tools"时追加）：search_memory / update_memory / forget_memory / recent_memories / search_dialogue / list_dialogues / delete_dialogue / list_topics
- Gateway 内置工具（每次都发）：web_search / fetch_url / create_todo / update_todo / delete_todo
- ref_update：不发给 LLM，仅 Gateway 后端调用
- ⚠️ 2026-05-29 变更：search_memory 从 CORE_TOOLS 移至 EXTENDED_TOOLS，防止 LLM 主动二次调用导致 token 爆炸（详见下方第十五节）

## 九、数据存储分布
- **memory.db**：记忆卡片(memories) + 历史快照(memory_history，每卡限2条) + 实体词典(entity_dict) + 对话暂存(dialogue相关表)
- **gateway.db**：对话(conversations + messages) + 日记(diary) + 摘要(summaries) + 待办(todos) + 睡前故事(bedtime_stories)

## 十、记忆引擎
六层架构：根骨 → 日记 → 点记忆(记忆卡片) → 线记忆(对话摘要) → 即时记忆(历史上下文) →  补充记忆(对话暂存)

## 十一、页面结构
- **首页**（门面）/：计时器 + 宣言 + 四个入口按钮 
- **聊天页** /chat：对话 
- **房间** /room：日记本(/room/diary) + 睡前故事(/room/stories) + todo list 
- **记忆页** /memory：记忆卡片(/memory/cards) + 对话缓存(/room/dialogue) + 对话摘要
- **设置页** /settings：根骨提示词 + API配置 + 头像设置+ 参数
  - 全局 temperature 滑块已接入，变更如下：

1. config.json / DEFAULT_CONFIG
顶层新增 "temperature": 1（与 context_window 同级）
现有 config.json 已写入该字段
2. 后端配置链路
新增 clamp_temperature()：范围 0–1，步长 0.05，缺省 1
normalize_config、GET /api/config、POST /api/config 均读写该字段
3. 设置页 /settings
在「对话参数」区增加 Temperature 滑块（0–1，步长 0.05）
实时显示当前值，loadConfig / saveConfig 已对接
4. 主对话 API
stream_chat_with_tools 从配置读取 temperature，写入主对话请求 body
摘要、日记、意图判断等系统调用不受影响（意图判断仍固定 temperature: 0）

## 十二、导航栏
首页 / 聊天 / 房间 / 记忆 / 设置
（原记忆后台端口8003已合并进Gateway /memory路由，memory-admin.service已退役）

## 十三、远期规划
- Core Blocks（根骨机制）：human / persona / covenant block，更新需审核可回滚
- 实时状态感知：session_state
- 关系边：暂时搁置

## 十四、已砍掉 / 远期再议
- ❌ 权重层/淡忘复活（等卡片几百条以上再议）
- ❌ 自动抽取写入路径（手动写入足够）
- ❌ MCP合并进Gateway（2026-05-15 取消）

## 十五、bug 修复记录
### 2026-05-29：search_memory embedding 回灌导致 token 爆炸
- **现象**：LLM 在生成中主动调用 search_memory，Gateway 把 MCP 返回的完整 JSON（含每张卡 768 维 embedding 向量，每张~17KB）原样作为 tool message 回灌，单轮 input_tokens 从 ~8k 飙到 ~64k（limit=5）甚至 ~107k（limit=10）
- **根因**：call_mcp_tool() 未剥离 embedding 字段
- **修复**：
  1. 新增 _strip_search_memory_embeddings()：对 search_memory 返回的 JSON 剥离每条记录的 embedding 字段后再写入 tool message
  2. search_memory 从 CORE_TOOLS 移至 EXTENDED_TOOLS，LLM 默认轮次不再看到该工具，避免主动二次调用
- **ref 不受影响**：_auto_ref_from_reply_async 使用预检索阶段传入的 injected_memory_vectors，不读 tool message 中的 embedding

## 一、系统组件
1. Gateway（端口8001）：前端页面（首页/聊天/房间/记忆/设置）+ 请求整理 + 上下文注入 + 流式SSE + Tool use分发 
2. MCP记忆服务（端口8002）：记忆卡增删改查 + embedding + 语义/关键词检索 + 对话暂存
3. LLM：Claude API（OpenAI兼容格式）
4. Nginx：HTTPS入口（待配置）

## 二、架构
Gateway（端口8001）
  ↓ LLM API（OpenAI兼容，流式SSE）
  ↓ API预设快速切换
  ↓ 意图判断 + embedding → search_memory → 注入记忆
  ↓ Tool use → MCP服务(8002) / Gateway内置工具(web_search, fetch_url, create_todo, update_todo, delete_todo)
  ↓ 写入类工具短路（SHORT_CIRCUIT_TOOLS，省第二轮）
  ↓ 对话存储 gateway.db
  ↓ ref余弦自动判定 → 回写last_used_at
  ↓ remember → SSE推送toast
  ↓ dreaming → 异步日记
  ↓ echo → todo 催促
  ↓ 摘要注入 + 自动摘要
  ↓ 记忆管理 /memory
  ↓ 房间 /room
  ↓ 图片发送 + 文件上传

MCP记忆服务（端口8002）— 独立运行
  ↓ memory_mcp_http.py + embedding_utils.py
  ↓ memory.db
  ↓ 打分引擎（FinalScore + 阈值0.50 + MMR）
  ↓ 对话暂存

## 三、调用流程
前端 → Gateway → Claude API → 返回tool_use → Gateway拦截 → 调MCP服务(8002) → 结果回传 → 继续生成 → SSE流式输出到前端

## 四、技术栈
- 服务器：腾讯云（2核2GB内存，40G SSD） + Python环境
- 数据库：SQLite × 2（memory.db 记忆+对话暂存 + gateway.db 对话/日记/摘要）
- 前端：Gateway单文件(gateway.py)内嵌HTML模板
- 服务管理：systemd × 2（gateway / memory-mcp）

## 五、文件路径
【记忆库相关】
- 数据库：/home/ubuntu/memory_mcp/memory.db
- 核心代码：/home/ubuntu/memory_mcp/memory_mcp_http.py
- Embedding工具：/home/ubuntu/memory_mcp/embedding_utils.py
- 环境文件：/etc/memory-mcp.env
- 服务文件：/etc/systemd/system/memory-mcp.service

【Gateway相关】
- 数据库：/home/ubuntu/gateway/gateway.db
- 主程序：/home/ubuntu/gateway/gateway.py
- 配置：/home/ubuntu/gateway/config.json
- 服务文件：/etc/systemd/system/gateway.service
- 认证密码：/home/ubuntu/memory_mcp/admin.env（记忆页HTTPBasic）

## 六、Gateway 配置
- config.json：含 assistants 数组 + context_window + memory_inject_count + auto_summary_trigger + summary_inject_count
- main 助手下有 presets 数组 + active_preset（API预设快速切换）
- 每个助手独立配置（Base URL / Key / 模型 / 提示词）

## 七、MCP 工具（11个，AI 可见10个）
- AI 可见：remember / search_memory / save_dialogue / update_memory / forget_memory / recent_memories / search_dialogue / list_dialogues / delete_dialogue / list_topics
- AI 不可见：ref_update（ref_update 已从 AI 可用工具列表移除（不在 CORE_TOOLS 中），MCP 端接口保留，Gateway 后端 _writeback_refs_async 异步调用）

## 八、工具分组加载
- CORE_TOOLS（每次都发）：remember / search_memory / save_dialogue
- EXTENDED_TOOLS（用户消息含关键词时追加）：update_memory / forget_memory / recent_memories / search_dialogue / list_dialogues / delete_dialogue / list_topics
- Gateway 内置工具（每次都发）：web_search / fetch_url / create_todo / update_todo / delete_todo
- ref_update：不发给 LLM，仅 Gateway 后端调用

## 九、数据存储分布
- **memory.db**：记忆卡片(memories) + 历史快照(memory_history，每卡限2条) + 实体词典(entity_dict) + 对话暂存(dialogue相关表)
- **gateway.db**：对话(conversations + messages) + 日记(diary) + 摘要(summaries) + 待办(todos) + 睡前故事(bedtime_stories)

## 十、记忆引擎
六层架构：根骨 → 日记 → 点记忆(记忆卡片) → 线记忆(对话摘要) → 即时记忆(历史上下文) →  补充记忆(对话暂存)

## 十一、页面结构
- **首页**（门面）/：计时器 + 宣言 + 四个入口按钮 
- **聊天页** /chat：对话 
- **房间** /room：日记本(/room/diary) + 睡前故事(/room/stories) + todo list 
- **记忆页** /memory：记忆卡片(/memory/cards) + 对话缓存(/room/dialogue) + 对话摘要
- **设置页** /settings：根骨提示词 + API配置 + 头像设置+ 参数
  - 全局 temperature 滑块已接入，变更如下：

1. config.json / DEFAULT_CONFIG
顶层新增 "temperature": 1（与 context_window 同级）
现有 config.json 已写入该字段
2. 后端配置链路
新增 clamp_temperature()：范围 0–1，步长 0.05，缺省 1
normalize_config、GET /api/config、POST /api/config 均读写该字段
3. 设置页 /settings
在「对话参数」区增加 Temperature 滑块（0–1，步长 0.05）
实时显示当前值，loadConfig / saveConfig 已对接
4. 主对话 API
stream_chat_with_tools 从配置读取 temperature，写入主对话请求 body
摘要、日记、意图判断等系统调用不受影响（意图判断仍固定 temperature: 0）

## 十二、导航栏
首页 / 聊天 / 房间 / 记忆 / 设置
（原记忆后台端口8003已合并进Gateway /memory路由，memory-admin.service已退役）

## 十三、远期规划
- Core Blocks（根骨机制）：human / persona / covenant block，更新需审核可回滚
- 实时状态感知：session_state
- 关系边：暂时搁置

## 十四、已砍掉 / 远期再议
- ❌ 权重层/淡忘复活（等卡片几百条以上再议）
- ❌ 自动抽取写入路径（手动写入足够）
- ❌ MCP合并进Gateway（2026-05-15 取消）