内容
# Kiro 总回忆
你是否曾经告诉 Kiro “就像我们昨天讨论的那样”，却发现它根本不知道你在说什么？
**总回忆** 为 Kiro 提供了它所缺失的记忆。
## 问题
1. **会话是隔离的**：每个 Kiro 会话都是全新的。昨天的架构讨论？没了。
2. **项目不共享知识**：你的偏好（测试风格、包管理器、模式）不会在项目之间被记住。
3. **命令行和 IDE 是分开的**：Kiro 命令行中的对话与 Kiro IDE 不相连。
**总回忆索引每个 Kiro 对话并提供语义搜索。** 通过*含义*而非关键词查找讨论。
## 快速入门
### 作为 Kiro 力量（推荐，仅限 IDE）
1. 在 Kiro IDE 中：力量面板 → **从 GitHub 添加力量**
2. 输入：`https://github.com/danilop/kiro-total-recall`
3. 当你提到“recall”、“remember”或“past conversation”时，力量会自动激活。
### 手动 MCP 设置（命令行和 IDE）
将以下内容添加到 `~/.kiro/settings/mcp.json`（此配置由命令行和 IDE 共享）：
```json
{
"mcpServers": {
"total-recall": {
"command": "uvx",
"args": ["--from", "git+https://github.com/danilop/kiro-total-recall", "kiro-total-recall"]
}
}
}
```
**重启 Kiro 命令行/IDE** 后添加。MCP 服务器仅在启动时加载。
### 验证安装
在 Kiro 命令行中：`/mcp` 应该列出 `total-recall`
在 Kiro IDE 中：检查 MCP 服务器面板
## 工作原理
```
┌─────────────────────────────────────────────────────────────────────────┐
│ Kiro 命令行和 IDE │
│ ┌──────────────────────────┐ ┌──────────────────────────────────┐ │
│ │ 命令行：SQLite 数据库 │ │ IDE：.chat JSON 文件 │ │
│ │ ~/Library/App Support/ │ │ ~/Library/App Support/Kiro/ │ │
│ │ kiro-cli/data.sqlite3 │ │ User/globalStorage/.../*.chat │ │
│ └────────────┬─────────────┘ └─────────────┬────────────────────┘ │
│ └────────────────┬───────────────┘ │
│ ▼ │
│ ┌───────────────────────┐ │
│ │ 统一加载器 │ │
│ └───────────┬───────────┘ │
└────────────────────────────────┼────────────────────────────────────────┘
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ Kiro 总回忆 │
│ ┌─────────┐ ┌──────────┐ ┌─────────┐ ┌────────────────────┐ │
│ │ 加载器 │───▶│ 索引器 │───▶│ 查询 │───▶│ MCP 服务器 │ │
│ │ 命令行+IDE │ │ 384 维 │ │ 余弦 │ │ 4 个搜索工具 │ │
│ └─────────┘ └────┬─────┘ └─────────┘ └────────────────────┘ │
│ ▼ │
│ ~/.cache/kiro-total-recall/embeddings.pkl │
└─────────────────────────────────────────────────────────────────────────┘
```
### 索引：使搜索更快
在第一次搜索时，总回忆：
1. **加载** 命令行（SQLite）和 IDE（.chat 文件）中的所有消息
2. **嵌入** 每个消息使用 [all-MiniLM-L6-v2](https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2)（384 维向量）
3. **缓存** 嵌入到 `~/.cache/kiro-total-recall/embeddings.pkl`
后续搜索很快，因为：
- **指纹识别**：仅在对话更改时重新构建
- **增量更新**：新消息被嵌入；现有嵌入从缓存中加载
- **基于哈希的重复数据删除**：相同的文本 = 相同的嵌入（无需重新计算）
## 功能
- **语义搜索**：按含义查找，而不仅仅是关键词
- **双源**：搜索命令行和 IDE 对话
- **上下文窗口**：查看每个匹配项周围的消息
- **日期过滤**：按时间范围（ISO 8601）过滤
- **增量索引**：仅处理新对话
- **内存限制**：可配置的 RAM 使用量（默认：1/3 RAM）
## MCP 工具
| 工具 | 范围 | 用例 |
|------|-------|----------|
| `search_project_history` | 当前工作区 | *此* 代码库中的错误、决策 |
| `search_global_history` | 所有工作区 | 所有工作中的偏好、模式 |
| `search_cli_history` | 仅命令行 | Kiro 命令行对话 |
| `search_ide_history` | 仅 IDE | Kiro IDE 对话 |
### 参数
所有工具都接受：
| 参数 | 默认值 | 描述 |
|-----------|---------|-------------|
| `query` | 必需 | 搜索关键词或句子 |
| `after` | 无 | 过滤到此日期及之后的邮件（包含）。ISO 8601 格式。 |
| `before` | 无 | 过滤到此日期之前的邮件（不包含）。ISO 8601 格式。 |
| `context_size` | 3 | 每个匹配项的前后消息 |
| `threshold` | 0.2 | 最小相似度（0-1，越高越严格） |
| `max_results` | 10 | 返回的最大结果数 |
| `offset` | 0 | 跳过结果（用于分页） |
### 日期过滤示例
```python
# 特定某天的消息
search_project_history(query="auth bug", after="2025-01-15", before="2025-01-16")
# 过去一周的消息
search_project_history(query="refactoring", after="2025-01-25")
# 一月内的消息
search_project_history(query="database", after="2025-01-01", before="2025-02-01")
```
### 响应结构
```json
{
"results": [
{
"matched_message": {
"role": "assistant",
"content": "要修复身份验证错误...",
"timestamp": "2025-01-15T10:30:00",
"workspace": "/Users/dev/myproject",
"session_id": "abc123",
"uuid": "msg-456",
"source": "cli"
},
"score": 0.8542,
"context": [
{"role": "user", "content": "如何修复此身份验证错误?", "timestamp": "...", "is_match": false},
{"role": "assistant", "content": "要修复身份验证错误...", "timestamp": "...", "is_match": true}
]
}
],
"query": "authentication bug fix",
"total_matches": 25,
"offset": 0,
"has_more": true,
"hint": "显示 1-10，共 25 个匹配项。使用 offset: 10 获取更多。"
}
```
## 使用示例
自然地提问：
```
"我们如何修复了那个身份验证错误？"
"我们讨论了什么数据库模式？”
"我的错误处理方法是什么？”
"查找我们上周的 React 组件讨论"
```
或直接使用工具：
```python
search_project_history(query="authentication bug fix")
search_global_history(query="React 组件模式")
search_cli_history(query="deployment", after="2025-01-01")
```
## 配置
创建 `~/.config/kiro-total-recall/config.toml` 以自定义：
```toml
[sources.cli]
enabled = true
paths = [
"~/Library/Application Support/kiro-cli/data.sqlite3",
"~/.local/share/kiro-cli/data.sqlite3",
"~/AppData/Roaming/kiro-cli/data.sqlite3",
]
[sources.ide]
enabled = true
patterns = [
"~/Library/Application Support/Kiro/User/globalStorage/kiro.kiroagent/*/*.chat",
"~/.config/Kiro/User/globalStorage/kiro.kiroagent/*/*.chat",
"~/AppData/Roaming/Kiro/User/globalStorage/kiro.kiroagent/*/*.chat",
]
[embedding]
model = "all-MiniLM-L6-v2"
cache_dir = "~/.cache/kiro-total-recall"
[search]
default_threshold = 0.2
default_max_results = 10
default_context_window = 3
[memory]
fraction = 0.33 # 使用 1/3 RAM
# limit_mb = 512 # 或设置显式限制
```
## 内存管理
总回忆限制内存索引大小以防止内存使用过高。默认情况下，它使用物理 RAM 的 1/3。当达到限制时，最旧的会话将从索引中排除（保留最新的会话）。
| 变量 | 描述 | 默认值 |
|----------|-------------|---------|
| `KIRO_RECALL_MEMORY_LIMIT_MB` | 以 MB 为单位覆盖内存限制 | 1/3 RAM |
| `KIRO_RECALL_NO_MEMORY_LIMIT` | 设置为任意值以禁用限制 | - |
## 测试
```bash
# 测试服务器启动
uvx kiro-total-recall
# 按 Ctrl+C 退出
# 直接测试搜索
uv run python -c "
from kiro_total_recall.query import search_conversations
result = search_conversations(query='bug fix', max_results=3)
print(f'Found {result.total_matches} matches')
"
```
## 项目结构
```
kiro-total-recall/
├── POWER.md # Kiro Power 清单 + 控制
├── mcp.json # Power 的 MCP 服务器配置
├── config.default.toml # 默认配置
├── src/kiro_total_recall/
│ ├── server.py # FastMCP 服务器，工具定义
│ ├── query.py # 搜索引擎，重复数据删除
│ ├── indexer.py # 嵌入，缓存，指纹识别
│ ├── loader.py # 统一加载器（命令行 + IDE）
│ ├── cli_loader.py # SQLite 解析命令行
│ ├── ide_loader.py # JSON 解析 IDE .chat 文件
│ ├── config.py # 配置管理
│ └── models.py # Pydantic 数据模型
├── pyproject.toml
└── LICENSE
```
## 技术细节
| 组件 | 技术 |
|-----------|------------|
| 嵌入模型 | [all-MiniLM-L6-v2](https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2)（384 维） |
| 向量搜索 | 通过 NumPy 点积的余弦相似度 |
| 缓存格式 | 带文件锁的 Python pickle |
| MCP 框架 | [FastMCP](https://github.com/jlowin/fastmcp) |
| 包管理器 | [uv](https://docs.astral.sh/uv/) |
## 许可证
[MIT 许可证](LICENSE)
