234 lines
5.2 KiB
Markdown
234 lines
5.2 KiB
Markdown
# 记忆系统维护指南
|
||
|
||
## 日常维护任务
|
||
|
||
### 定期清理
|
||
```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文件
|
||
- 清理重复内容
|
||
- 归档过期短期记忆
|
||
|
||
### 查询优化
|
||
- 使用分页查询大量数据
|
||
- 优先使用索引字段过滤
|
||
- 缓存常用查询结果
|