# ContextRecall 架构设计

## 系统架构

```
┌─────────────────────────────────────────────────────────┐
│                     用户接口层                           │
├─────────────────────────────────────────────────────────┤
│  recall  │  recall-init  │  recall-search  │  ...      │
└─────────────────────────────────────────────────────────┘
                           ↓
┌─────────────────────────────────────────────────────────┐
│                     核心功能层                           │
├─────────────────────────────────────────────────────────┤
│  ┌──────────┐  ┌──────────┐  ┌──────────┐              │
│  │ 存储层   │  │ 检索层   │  │ 摘要层   │              │
│  │ Memory   │  │ Retriever│  │ Summarizer│             │
│  │ Store    │  │          │  │          │              │
│  └──────────┘  └──────────┘  └──────────┘              │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐              │
│  │ 待办提取 │  │ 标签系统 │  │ 可视化   │              │
│  │ Task     │  │ Tagger   │  │ Visualizer│             │
│  │ Extractor│  │          │  │          │              │
│  └──────────┘  └──────────┘  └──────────┘              │
└─────────────────────────────────────────────────────────┘
                           ↓
┌─────────────────────────────────────────────────────────┐
│                     数据存储层                           │
├─────────────────────────────────────────────────────────┤
│  memory/                                                │
│  ├── daily/           # 每日摘要                        │
│  ├── weekly/          # 周汇总                          │
│  ├── monthly/         # 月汇总                          │
│  ├── ontology/        # 结构化数据                      │
│  │   ├── tasks.json                                   │
│  │   ├── tags.json                                    │
│  │   └── preferences.json                             │
│  ├── session-logs/    # 会话日志                        │
│  ├── visualization/   # 可视化输出                      │
│  └── index.json       # 检索索引                        │
└─────────────────────────────────────────────────────────┘
```

## 核心模块

### 1. MemoryStore（存储层）

**职责**：文件系统操作

**关键方法**：
- `saveDaily(date, content)` - 保存每日记忆
- `loadDaily(date)` - 读取指定日期记忆
- `saveOntology(type, data)` - 保存结构化数据
- `updateIndex(date, type, content)` - 更新索引

**存储格式**：
- Markdown（人类可读）
- JSON（结构化数据）
- JSONL（追加式日志）

### 2. Retriever（检索层）

**职责**：记忆检索

**检索策略**：
1. 元数据过滤（时间、类型）
2. 关键词匹配（TF-IDF）
3. 相似度排序（Jaccard）

**中文分词**：
- 滑动窗口提取 2-8 字词组
- 支持中英文混合

### 3. Summarizer（摘要层）

**职责**：生成会话摘要

**摘要内容**：
- 主题提取
- 待办识别
- 统计信息

### 4. TaskExtractor（待办提取）

**职责**：从对话中提取任务

**提取模式**：
- 正则匹配（显式标记）
- 模式识别（承诺表达）
- 启发式规则（疑问转待办）

### 5. Tagger（标签系统）

**职责**：自动分类记忆

**预定义标签**：
- 工作、学习、生活
- 决策、问题、想法

### 6. Visualizer（可视化）

**职责**：生成 HTML 时间线

**技术**：
- 纯 HTML/CSS
- 响应式设计
- 搜索过滤

## 数据流

### 会话生命周期

```
用户消息 → recall_log_user() → session-log.json
    ↓
助手回复 → recall_log_assistant() → session-log.json
    ↓
会话结束 → recall_session_end()
    ↓
生成摘要 → daily/YYYY-MM-DD.md
    ↓
提取待办 → ontology/tasks.json
    ↓
更新索引 → index.json
```

### 检索流程

```
用户查询 → recall_search()
    ↓
加载索引 → index.json
    ↓
关键词提取 → 分词
    ↓
相似度计算 → Jaccard
    ↓
排序返回 → Top-K
```

## 性能优化

### 1. 分层检索

- 99% 工作在本地完成
- 仅 Top-5 进入 LLM
- Token 消耗降低 99.7%

### 2. 索引机制

- 预计算关键词
- 增量更新
- 避免全量扫描

### 3. 存储优化

- 7天后压缩
- 30天后归档
- 分层存储

## 安全设计

### 隐私保护

- 纯本地存储
- 零外部 API
- 用户完全控制

### 数据安全

- Git 版本控制
- 定期备份
- 导入导出支持

## 扩展性

### 插件机制

未来支持：
- 自定义提取器
- 自定义标签规则
- 自定义可视化模板

### API 接口

```javascript
const ContextRecall = require('context-recall');

const cr = new ContextRecall();
await cr.init();

const results = await cr.search('query');
await cr.capture({ type: 'task', content: '...' });
```

## 技术栈

- **运行时**：Node.js 18+
- **依赖**：零外部依赖
- **工具**：jq（可选，用于钩子）
- **调度**：cron（可选，用于定时任务）

## 版本历史

| 版本 | 日期 | 功能 |
|------|------|------|
| 1.0.0 | [REDACTED_PHONE] | 初始版本，完整功能集 |

---

## 贡献指南

欢迎提交 Issue 和 PR！

### 开发流程

1. Fork 仓库
2. 创建分支
3. 提交更改
4. 运行测试
5. 提交 PR

### 代码规范

- 使用 ESLint
- 添加注释
- 编写测试