Initial commit

skills/memory/references/advanced/maintenance.md

@@ -0,0 +1,233 @@
+# 记忆系统维护指南
+
+## 日常维护任务
+
+### 定期清理
+```bash
+# 清理7天前的短期记忆
+find .ai-runtime/memory/short-term/ -mtime +7 -delete
+
+# 检查episodic目录结构
+find .ai-runtime/memory/episodic/ -type f -name "*.md" | head -20
+```
+
+### 索引更新
+```bash
+# 手动刷新记忆索引
+python3 -c "from memory_discovery import MemoryDiscovery; d=MemoryDiscovery('.ai-runtime/memory'); d.refresh()"
+```
+
+### 一致性检查
+- 验证所有episodic文件都有有效的YAML front matter
+- 检查时间戳格式统一性
+- 确认标签命名规范
+
+## 事件添加流程
+
+### 1. 创建事件文件
+```bash
+# 创建目录结构（如果不存在）
+mkdir -p .ai-runtime/memory/episodic/$(date +%Y/%m/%d)
+
+# 创建事件文件
+vim .ai-runtime/memory/episodic/$(date +%Y/%m/%d)/event-description.md
+```
+
+### 2. YAML Front Matter 模板
+```yaml
+---
+id: unique-event-id
+type: event|decision|error|meeting|milestone
+level: day
+timestamp: "2025-11-14T10:30:00"
+tags: [tag1, tag2, tag3]
+related: [related-event-id-1, related-event-id-2]
+---
+
+# 事件标题
+
+## 时间
+2025-11-14 10:30:00
+
+## 标签
+tag1, tag2, tag3
+
+## 内容
+详细的事件描述，包括：
+- 背景信息
+- 决策过程
+- 结果和影响
+- 后续行动项
+
+## 相关事件
+- [related-event-id-1](link-to-related)
+- [related-event-id-2](link-to-related)
+```
+
+### 3. 事件类型规范
+
+| 类型 | 描述 | 示例 |
+|------|------|------|
+| `event` | 一般事件 | 代码审查、部署上线 |
+| `decision` | 关键决策 | 架构选择、技术栈变更 |
+| `error` | 错误和问题 | 生产故障、构建失败 |
+| `meeting` | 会议纪要 | 团队会议、客户会议 |
+| `milestone` | 里程碑 | 项目启动、版本发布 |
+
+### 4. 标签规范
+
+**技术标签**:
+- `architecture` - 架构相关
+- `database` - 数据库相关
+- `frontend` - 前端相关
+- `backend` - 后端相关
+- `devops` - 运维相关
+- `security` - 安全相关
+
+**活动标签**:
+- `planning` - 规划阶段
+- `development` - 开发阶段
+- `testing` - 测试阶段
+- `deployment` - 部署阶段
+- `maintenance` - 维护阶段
+
+**结果标签**:
+- `success` - 成功
+- `failure` - 失败
+- `improvement` - 改进
+- `regression` - 回归
+
+## 记忆固化策略
+
+### 短期记忆 → 长期记忆
+
+**触发条件**:
+- 识别出可复用的技术模式
+- 积累了足够的使用经验
+- 形成了最佳实践
+
+**固化流程**:
+1. 从短期记忆提取关键信息
+2. 整理为结构化文档
+3. 移动到 `long-term/` 目录
+4. 更新相关引用
+5. 添加到知识图谱
+
+**示例**:
+```bash
+# 提取OAuth2.0集成经验
+cp .ai-runtime/memory/short-term/oauth-integration-notes.md .ai-runtime/memory/long-term/oauth-integration-patterns.md
+
+# 更新引用
+echo "- oauth-integration-patterns.md" >> .ai-runtime/memory/long-term/index.md
+```
+
+### 工作记忆 → 情景记忆
+
+**触发条件**:
+- 任务完成
+- 关键决策做出
+- 错误发生并解决
+- 里程碑达成
+
+**固化流程**:
+1. 自动生成事件ID
+2. 创建时间戳
+3. 提取上下文信息
+4. 添加到episodic时间线
+5. 更新相关链接
+
+**自动固化**:
+```bash
+# 使用/runtime.remember命令
+/runtime.remember "完成了用户认证模块重构，采用JWT替代session"
+```
+
+## 质量保证
+
+### 一致性检查脚本
+```python
+#!/usr/bin/env python3
+"""记忆系统质量检查工具"""
+
+import sys
+from pathlib import Path
+from memory_discovery import MemoryDiscovery
+
+def check_memory_quality(memory_root: Path):
+    """检查记忆系统质量"""
+    discovery = MemoryDiscovery(str(memory_root))
+
+    issues = []
+
+    # 检查episodic文件
+    for event in discovery.events:
+        # 检查必需字段
+        if not event.id:
+            issues.append(f"事件缺少ID: {event.path}")
+        if not event.timestamp:
+            issues.append(f"事件缺少时间戳: {event.path}")
+        if not event.title:
+            issues.append(f"事件缺少标题: {event.path}")
+
+        # 检查时间合理性
+        if event.timestamp and event.timestamp > datetime.now():
+            issues.append(f"事件时间戳为未来: {event.path}")
+
+    return issues
+
+if __name__ == "__main__":
+    memory_root = Path(".ai-runtime/memory")
+    issues = check_memory_quality(memory_root)
+
+    if issues:
+        print("发现以下质量问题:")
+        for issue in issues:
+            print(f"  - {issue}")
+        sys.exit(1)
+    else:
+        print("记忆系统质量检查通过")
+```
+
+### 数据备份策略
+
+**自动备份**:
+- 每日备份episodic目录
+- 每周备份long-term目录
+- 每月备份完整记忆系统
+
+**备份脚本**:
+```bash
+#!/bin/bash
+# 记忆系统备份脚本
+
+BACKUP_DIR=".ai-runtime/backups"
+TIMESTAMP=$(date +%Y%m%d_%H%M%S)
+
+mkdir -p $BACKUP_DIR
+
+# 备份episodic记忆
+tar -czf $BACKUP_DIR/episodic_$TIMESTAMP.tar.gz .ai-runtime/memory/episodic/
+
+# 备份long-term记忆
+tar -czf $BACKUP_DIR/long-term_$TIMESTAMP.tar.gz .ai-runtime/memory/long-term/
+
+echo "备份完成: $TIMESTAMP"
+```
+
+## 性能优化
+
+### 索引优化
+- 定期重建事件索引
+- 优化时间范围查询
+- 维护标签倒排索引
+
+### 存储优化
+- 压缩历史episodic文件
+- 清理重复内容
+- 归档过期短期记忆
+
+### 查询优化
+- 使用分页查询大量数据
+- 优先使用索引字段过滤
+- 缓存常用查询结果

skills/memory/references/core/architecture.md

@@ -0,0 +1,111 @@
+# 记忆系统架构详解
+
+## 分层记忆架构
+
+AI Runtime采用三层记忆系统，模拟人类大脑的记忆机制：
+
+```
+短期记忆（工作记忆） ← 当前会话上下文 (7±2组块限制)
+    ↓ 固化
+长期记忆（语义记忆） ← 跨项目技术知识 (结构化知识图谱)
+    ↓ 时间戳
+情景记忆（体验记忆） ← 项目历史事件 (时间线序列)
+```
+
+## 设计原则详述
+
+### 短期记忆 (short-term/)
+- **位置**: `.ai-runtime/memory/short-term/`
+- **内容**: 当前会话上下文、任务栈、工作假设
+- **容量**: 类似人脑7±2组块限制
+- **生命周期**: 实时衰减，支撑当前任务
+- **管理**: 自动清理过期内容（7天）
+
+### 长期记忆 (long-term/)
+- **位置**: `.ai-runtime/memory/long-term/`
+- **内容**: 跨项目技术知识、设计模式、代码质量经验
+- **特点**: 结构化整理，支持快速检索
+- **用途**: 提供经验基础上的智能建议
+
+### 情景记忆 (episodic/)
+- **位置**: `.ai-runtime/memory/episodic/`
+- **内容**: 项目历史、关键决策、错误教训、会议纪要
+- **格式**: 时间线记录 + 事件详情
+- **特点**: 可追溯性，支持复杂SQL风格查询
+
+## 文件夹结构详解
+
+### episodic/ - 情景记忆存储
+
+**目录结构**:
+```
+episodic/
+├── 2025/
+│   ├── 11/
+│   │   ├── 14/
+│   │   │   ├── event-001.md
+│   │   │   └── meeting-001.md
+│   │   └── 15/
+│   └── 12/
+└── timeline.md (自动生成的时间线索引)
+```
+
+**文件格式规范**:
+- 必须使用YAML front matter
+- 支持多级时间目录结构
+- 自动时间推断机制
+
+### long-term/ - 长期记忆存储
+
+**内容分类**:
+- `project-context.md` - 项目架构记忆
+- `tech-stack.md` - 技术栈知识
+- `design-patterns.md` - 设计模式经验
+- `user-preferences.md` - 用户偏好记录
+
+### short-term/ - 短期记忆存储
+
+**文件类型**:
+- `consciousness.md` - 当前意识流状态
+- `task-stack.md` - 任务栈快照
+- `working-hypothesis.md` - 工作假设
+
+## 记忆生命周期管理
+
+### 固化流程
+
+1. **短期 → 长期固化**:
+   - 识别有价值模式和知识
+   - 整理为结构化文档
+   - 移动到 `long-term/` 目录
+   - 更新知识图谱索引
+
+2. **工作记忆 → 情景记忆**:
+   - 关键事件自动记录 (`/runtime.remember`)
+   - 生成时间戳和上下文
+   - 添加到episodic时间线
+
+### 清理策略
+
+**自动清理**:
+- 短期记忆: 7天过期自动删除
+- 工作状态: 会话结束后清理
+- 临时假设: 验证后清理
+
+**手动归档**:
+- 重要事件移动到归档目录
+- 合并相似记忆条目
+- 更新索引和引用关系
+
+## 索引和检索机制
+
+### 自动索引生成
+- episodic目录扫描生成timeline.md
+- 基于文件名和front matter的时间推断
+- 支持多级时间聚合（年/月/日）
+
+### 检索优化
+- 时间范围索引
+- 标签倒排索引
+- 类型分类索引
+- 全文搜索支持

skills/memory/references/examples/examples.md

@@ -0,0 +1,373 @@
+# 记忆系统使用示例
+
+## 快速开始
+
+### 环境准备
+```bash
+# 进入项目目录
+cd /path/to/ai-runtime
+
+# 进入记忆系统目录
+cd .ai-runtime/memory
+```
+
+### 第一个查询
+```bash
+# 查看所有记忆事件
+python3 memory_cli.py query
+
+# 查看今天的事件
+python3 memory_cli.py query --where "date='$(date +%Y-%m-%d)'"
+```
+
+## 情景记忆查询示例
+
+### 时间范围查询
+```bash
+# 查看本周事件
+python3 memory_cli.py query \
+    --where "date>='$(date -d 'last monday' +%Y-%m-%d)'" \
+    --order-by "timestamp desc"
+
+# 查看最近24小时的事件
+python3 memory_cli.py query \
+    --where "timestamp >= '$(date -d '24 hours ago' +%Y-%m-%dT%H:%M:%S)'" \
+    --order-by "timestamp desc"
+```
+
+### 类型过滤
+```bash
+# 查看所有决策
+python3 memory_cli.py query \
+    --where "type='decision'" \
+    --order-by "timestamp desc"
+
+# 查看错误事件
+python3 memory_cli.py query \
+    --where "type='error'" \
+    --select "timestamp,title,tags" \
+    --limit 10
+```
+
+### 标签查询
+```bash
+# 查找架构相关事件
+python3 memory_cli.py query \
+    --where "tags CONTAINS 'architecture'"
+
+# 查找安全相关决策
+python3 memory_cli.py query \
+    --where "type='decision' AND tags CONTAINS 'security'"
+```
+
+### 复杂组合查询
+```bash
+# 查找本月的重要架构决策
+python3 memory_cli.py query \
+    --where "date>='$(date +%Y-%m-01)' AND type='decision' AND tags CONTAINS 'architecture'" \
+    --order-by "timestamp desc" \
+    --limit 20
+```
+
+## 数据导出和分析
+
+### JSON格式导出
+```bash
+# 导出本周事件为JSON
+python3 memory_cli.py query \
+    --where "date>='$(date -d '7 days ago' +%Y-%m-%d)'" \
+    --format json \
+    --order-by "timestamp desc" > weekly-events.json
+```
+
+### 统计分析
+```bash
+# 统计各类型事件数量
+python3 memory_cli.py query \
+    --select "type" \
+    --format json | jq -r '.[].type' | sort | uniq -c | sort -nr
+
+# 统计热门标签
+python3 memory_cli.py query \
+    --select "tags" \
+    --format json | jq -r '.[].tags[]' | sort | uniq -c | sort -nr | head -10
+```
+
+### 时间线分析
+```bash
+# 生成每日事件数量统计
+python3 memory_cli.py query \
+    --select "date" \
+    --format json | jq -r '.[].date' | sort | uniq -c | sort
+```
+
+## 编程接口使用
+
+### Python集成示例
+```python
+#!/usr/bin/env python3
+"""记忆系统集成示例"""
+
+import sys
+from pathlib import Path
+from memory_discovery import MemoryDiscovery
+
+class MemoryAnalytics:
+    """记忆分析工具"""
+
+    def __init__(self, memory_root: str):
+        self.discovery = MemoryDiscovery(memory_root)
+
+    def get_recent_events(self, days: int = 7):
+        """获取最近N天的所有事件"""
+        import datetime
+        cutoff = datetime.datetime.now() - datetime.timedelta(days=days)
+
+        return self.discovery.query(
+            where=f"timestamp >= '{cutoff.isoformat()}'",
+            order_by="timestamp desc"
+        )
+
+    def get_events_by_type(self, event_type: str, limit: int = 50):
+        """按类型获取事件"""
+        return self.discovery.query(
+            where=f"type='{event_type}'",
+            order_by="timestamp desc",
+            limit=limit
+        )
+
+    def search_by_tags(self, tags: list, match_all: bool = True):
+        """按标签搜索"""
+        if not tags:
+            return []
+
+        conditions = []
+        for tag in tags:
+            conditions.append(f"tags CONTAINS '{tag}'")
+
+        operator = " AND " if match_all else " OR "
+        where_clause = operator.join(conditions)
+
+        return self.discovery.query(where=where_clause)
+
+    def get_event_summary(self, days: int = 30):
+        """生成事件摘要统计"""
+        events = self.get_recent_events(days)
+
+        summary = {
+            'total': len(events),
+            'by_type': {},
+            'by_tag': {},
+            'timeline': {}
+        }
+
+        for event in events:
+            # 按类型统计
+            summary['by_type'][event.type] = summary['by_type'].get(event.type, 0) + 1
+
+            # 按标签统计
+            for tag in event.tags:
+                summary['by_tag'][tag] = summary['by_tag'].get(tag, 0) + 1
+
+            # 按日期统计
+            date_str = event.date
+            summary['timeline'][date_str] = summary['timeline'].get(date_str, 0) + 1
+
+        return summary
+
+def main():
+    analytics = MemoryAnalytics('.ai-runtime/memory')
+
+    # 获取最近7天的事件摘要
+    summary = analytics.get_event_summary(7)
+    print(f"最近7天共记录 {summary['total']} 个事件")
+
+    # 显示类型分布
+    print("\n事件类型分布:")
+    for event_type, count in summary['by_type'].items():
+        print(f"  {event_type}: {count}")
+
+    # 显示热门标签
+    print("\n热门标签:")
+    sorted_tags = sorted(summary['by_tag'].items(), key=lambda x: x[1], reverse=True)
+    for tag, count in sorted_tags[:10]:
+        print(f"  {tag}: {count}")
+
+if __name__ == "__main__":
+    main()
+```
+
+### Web界面集成
+```python
+#!/usr/bin/env python3
+"""简单的记忆查询Web服务"""
+
+from flask import Flask, request, jsonify
+from memory_discovery import MemoryDiscovery
+
+app = Flask(__name__)
+discovery = MemoryDiscovery('.ai-runtime/memory')
+
+@app.route('/api/events', methods=['GET'])
+def get_events():
+    """查询事件API"""
+    where = request.args.get('where', '')
+    limit = int(request.args.get('limit', 50))
+    offset = int(request.args.get('offset', 0))
+    format_type = request.args.get('format', 'json')
+
+    events = discovery.query(where=where, limit=limit, offset=offset)
+    return discovery.format_events(events, format_type=format_type)
+
+@app.route('/api/stats', methods=['GET'])
+def get_stats():
+    """获取统计信息"""
+    days = int(request.args.get('days', 30))
+
+    import datetime
+    cutoff = datetime.datetime.now() - datetime.timedelta(days=days)
+    events = discovery.query(where=f"timestamp >= '{cutoff.isoformat()}'")
+
+    stats = {
+        'total': len(events),
+        'by_type': {},
+        'by_tag': {},
+        'date_range': {
+            'start': cutoff.date().isoformat(),
+            'end': datetime.date.today().isoformat()
+        }
+    }
+
+    for event in events:
+        stats['by_type'][event.type] = stats['by_type'].get(event.type, 0) + 1
+        for tag in event.tags:
+            stats['by_tag'][tag] = stats['by_tag'].get(tag, 0) + 1
+
+    return jsonify(stats)
+
+if __name__ == "__main__":
+    app.run(debug=True, port=5001)
+```
+
+## 自动化脚本
+
+### 每日摘要生成
+```bash
+#!/bin/bash
+# 生成每日记忆摘要
+
+DATE=$(date +%Y-%m-%d)
+OUTPUT_DIR=".ai-runtime/reports"
+mkdir -p $OUTPUT_DIR
+
+echo "# ${DATE} 记忆摘要" > $OUTPUT_DIR/daily-summary-${DATE}.md
+echo "" >> $OUTPUT_DIR/daily-summary-${DATE}.md
+
+echo "## 今日事件统计" >> $OUTPUT_DIR/daily-summary-${DATE}.md
+python3 memory_cli.py query --where "date='${DATE}'" --format json | jq '. | length' >> $OUTPUT_DIR/daily-summary-${DATE}.md
+
+echo "" >> $OUTPUT_DIR/daily-summary-${DATE}.md
+echo "## 今日事件列表" >> $OUTPUT_DIR/daily-summary-${DATE}.md
+python3 memory_cli.py query --where "date='${DATE}'" --select "timestamp,title,type" >> $OUTPUT_DIR/daily-summary-${DATE}.md
+
+echo "" >> $OUTPUT_DIR/daily-summary-${DATE}.md
+echo "## 热门标签" >> $OUTPUT_DIR/daily-summary-${DATE}.md
+python3 memory_cli.py query --where "date='${DATE}'" --select "tags" --format json | jq -r '.[].tags[]' | sort | uniq -c | sort -nr | head -5 >> $OUTPUT_DIR/daily-summary-${DATE}.md
+```
+
+### 定期维护脚本
+```bash
+#!/bin/bash
+# 记忆系统定期维护
+
+MEMORY_ROOT=".ai-runtime/memory"
+
+# 清理过期短期记忆（30天）
+find ${MEMORY_ROOT}/short-term/ -mtime +30 -delete
+
+# 检查episodic文件一致性
+python3 -c "
+from memory_discovery import MemoryDiscovery
+d = MemoryDiscovery('${MEMORY_ROOT}')
+invalid = [e for e in d.events if not e.timestamp or not e.title]
+if invalid:
+    print('发现无效事件:')
+    for e in invalid:
+        print(f'  {e.path}: 缺少必要字段')
+else:
+    print('所有事件文件有效')
+"
+
+# 生成维护报告
+REPORT_FILE=".ai-runtime/reports/maintenance-$(date +%Y%m%d).md"
+echo "# 记忆系统维护报告 - $(date)" > $REPORT_FILE
+echo "" >> $REPORT_FILE
+echo "## 统计信息" >> $REPORT_FILE
+echo "- Episodic事件数量: $(find ${MEMORY_ROOT}/episodic/ -name '*.md' | wc -l)" >> $REPORT_FILE
+echo "- Long-term文档数量: $(find ${MEMORY_ROOT}/long-term/ -name '*.md' | wc -l)" >> $REPORT_FILE
+echo "- Short-term文件数量: $(find ${MEMORY_ROOT}/short-term/ -name '*.md' | wc -l)" >> $REPORT_FILE
+```
+
+## 高级查询技巧
+
+### 正则表达式搜索
+```python
+# 使用Python进行高级搜索
+import re
+from memory_discovery import MemoryDiscovery
+
+discovery = MemoryDiscovery('.ai-runtime/memory')
+
+# 搜索包含特定关键词的事件
+keyword_events = []
+for event in discovery.events:
+    if re.search(r'OAuth|认证', event.title, re.IGNORECASE):
+        keyword_events.append(event)
+
+print(f"找到 {len(keyword_events)} 个相关事件")
+```
+
+### 时间序列分析
+```python
+# 分析事件的时间分布
+from collections import defaultdict
+from memory_discovery import MemoryDiscovery
+
+discovery = MemoryDiscovery('.ai-runtime/memory')
+events = discovery.query(order_by="timestamp asc")
+
+# 按小时统计
+hourly_stats = defaultdict(int)
+for event in events:
+    hour = event.timestamp.hour
+    hourly_stats[hour] += 1
+
+print("事件按小时分布:")
+for hour in sorted(hourly_stats.keys()):
+    print(f"  {hour:02d}:00: {hourly_stats[hour]} 个事件")
+```
+
+### 相关性分析
+```python
+# 分析标签共现关系
+from collections import defaultdict
+from memory_discovery import MemoryDiscovery
+
+discovery = MemoryDiscovery('.ai-runtime/memory')
+
+# 构建标签共现矩阵
+cooccurrence = defaultdict(lambda: defaultdict(int))
+for event in discovery.events:
+    tags = event.tags
+    for i, tag1 in enumerate(tags):
+        for tag2 in tags[i+1:]:
+            cooccurrence[tag1][tag2] += 1
+            cooccurrence[tag2][tag1] += 1
+
+# 显示最相关的标签对
+print("标签共现分析:")
+for tag1 in sorted(cooccurrence.keys()):
+    for tag2, count in sorted(cooccurrence[tag1].items(), key=lambda x: x[1], reverse=True):
+        if count > 1:  # 至少出现2次
+            print(f"  {tag1} + {tag2}: {count} 次")
+```

skills/memory/references/guides/tools.md

@@ -0,0 +1,266 @@
+# 记忆系统工具详解
+
+## memory_cli.py - 命令行查询工具
+
+### 核心功能
+提供SQL风格的命令行接口，支持复杂条件查询情景记忆事件。
+
+### 命令语法
+```bash
+python3 memory_cli.py query [选项...]
+```
+
+### 查询选项详解
+
+#### --select 字段选择
+```bash
+# 选择特定字段
+--select "id,timestamp,title"
+
+# 默认选择（不指定时）
+--select "id,timestamp,title"
+```
+
+#### --where 条件过滤
+支持SQL风格WHERE条件，字段包括：
+- `id`, `type`, `level`, `title`, `date`, `timestamp`
+- `tags` (支持 CONTAINS 操作)
+
+```bash
+# 基础条件
+--where "type='decision'"
+--where "date>='2025-11-14'"
+--where "tags CONTAINS 'architecture'"
+
+# 组合条件
+--where "date>='2025-11-14' AND tags CONTAINS 'decision'"
+--where "type='meeting' OR type='decision'"
+```
+
+#### --order-by 排序
+```bash
+# 单个字段排序
+--order-by "timestamp desc"
+--order-by "date asc"
+
+# 多个字段排序（暂不支持）
+```
+
+#### --limit / --offset 分页
+```bash
+--limit 20 --offset 0    # 第一页，20条
+--limit 20 --offset 20   # 第二页，20条
+```
+
+#### --format 输出格式
+```bash
+--format table   # 表格格式（默认）
+--format json    # JSON格式
+```
+
+### 使用示例
+
+#### 基础查询
+```bash
+# 查看所有事件
+python3 memory_cli.py query
+
+# 查看今天的事件
+python3 memory_cli.py query --where "date='2025-11-14'"
+```
+
+#### 高级查询
+```bash
+# 查找架构决策
+python3 memory_cli.py query \
+    --where "type='decision' AND tags CONTAINS 'architecture'" \
+    --order-by "timestamp desc" \
+    --limit 10
+
+# 搜索错误事件
+python3 memory_cli.py query \
+    --where "type='error'" \
+    --select "timestamp,title,tags" \
+    --format table
+```
+
+#### 时间范围查询
+```bash
+# 本周事件
+python3 memory_cli.py query \
+    --where "date>='2025-11-10' AND date<='2025-11-16'"
+
+# 最近7天
+python3 memory_cli.py query \
+    --where "timestamp >= '2025-11-07T00:00:00'" \
+    --order-by "timestamp desc"
+```
+
+## memory_discovery.py - 编程接口
+
+### 类概述
+
+#### MemoryDiscovery 类
+核心记忆发现和查询引擎。
+
+#### MemoryEvent 类
+单个记忆事件的索引信息数据类。
+
+### 编程接口
+
+#### 初始化
+```python
+from memory_discovery import MemoryDiscovery
+
+# 初始化发现器
+discovery = MemoryDiscovery("path/to/memory/root")
+```
+
+#### 刷新索引
+```python
+# 重新扫描episodic目录
+discovery.refresh()
+```
+
+#### SQL风格查询
+```python
+# 基础查询
+events = discovery.query()
+
+# 条件查询
+events = discovery.query(
+    where="date>='2025-11-14' AND tags CONTAINS 'architecture'",
+    order_by="timestamp desc",
+    limit=20,
+    offset=0
+)
+```
+
+#### 格式化输出
+```python
+# 表格格式
+output = discovery.format_events(events, format_type="table")
+
+# JSON格式
+output = discovery.format_events(events, format_type="json")
+
+# 自定义字段选择
+output = discovery.format_events(
+    events,
+    select=["id", "title", "date"],
+    format_type="table"
+)
+```
+
+### 事件解析协议
+
+#### 时间推断顺序
+1. YAML front matter `timestamp`/`time` 字段
+2. 正文 `## 时间` 段落第一行
+3. 文件名模式 `YYYYMMDD-HHMM.md`
+4. 文件名模式 `YYYYMMDD.md`
+5. 文件修改时间 (mtime)
+
+#### 标签解析顺序
+1. YAML front matter `tags` 数组
+2. 正文 `## 标签` 段落（逗号分隔）
+3. 空数组（无标签）
+
+#### 标题解析顺序
+1. YAML front matter `title`
+2. 正文第一个 `# ` 标题
+3. 文件名（去除扩展名）
+
+### 高级用法
+
+#### 自定义查询条件
+```python
+# 复杂的标签组合查询
+events = discovery.query(
+    where="tags CONTAINS 'architecture' AND (tags CONTAINS 'decision' OR tags CONTAINS 'design')"
+)
+```
+
+#### 批量处理
+```python
+# 分页处理大量事件
+page_size = 50
+all_events = []
+
+for offset in range(0, 1000, page_size):  # 最多1000条
+    batch = discovery.query(limit=page_size, offset=offset)
+    if not batch:
+        break
+    all_events.extend(batch)
+```
+
+#### 事件对象操作
+```python
+# 访问事件属性
+for event in events:
+    print(f"ID: {event.id}")
+    print(f"标题: {event.title}")
+    print(f"时间: {event.timestamp}")
+    print(f"标签: {event.tags}")
+    print(f"类型: {event.type}")
+
+    # 转换为字典
+    event_dict = event.to_dict()
+```
+
+## 工具集成
+
+### Shell脚本集成
+```bash
+# 创建查询别名
+alias memory-query="python3 .ai-runtime/memory/memory_cli.py query"
+
+# 快速查看今天事件
+memory-query --where "date='$(date +%Y-%m-%d)'"
+```
+
+### Python脚本集成
+```python
+#!/usr/bin/env python3
+import sys
+sys.path.insert(0, '.ai-runtime/memory')
+
+from memory_discovery import MemoryDiscovery
+
+def get_recent_decisions(days=7):
+    import datetime
+    cutoff = datetime.datetime.now() - datetime.timedelta(days=days)
+
+    discovery = MemoryDiscovery('.ai-runtime/memory')
+    return discovery.query(
+        where=f"type='decision' AND timestamp >= '{cutoff.isoformat()}'",
+        order_by="timestamp desc"
+    )
+```
+
+## 故障排除
+
+### 常见问题
+
+**查询无结果**
+- 检查WHERE条件语法
+- 验证字段名称拼写
+- 确认时间格式（YYYY-MM-DD）
+
+**事件不显示**
+- 检查文件路径结构（episodic/YYYY/MM/DD/）
+- 验证YAML front matter格式
+- 确认时间戳有效性
+
+**性能问题**
+- 使用LIMIT限制结果数量
+- 优化WHERE条件（先过滤时间范围）
+- 考虑分页查询大量数据
+
+### 调试技巧
+```python
+# 查看所有已解析事件
+discovery = MemoryDiscovery('.ai-runtime/memory')
+for event in discovery.events:
+    print(f"{event.id}: {event.title} ({event.date}) - {event.tags}")
+```