# ai_memo

**Repository Path**: penciltower/ai_memo

## Basic Information

- **Project Name**: ai_memo
- **Description**: memory respo
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-13
- **Last Updated**: 2026-06-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AI Memo - 项目记忆系统

基于 MiMo Code 的 "计算-记忆-进化" 框架实现的项目级 Agent 记忆系统。

## 特性

- **四层记忆体系**: Session / Project / Global / History，按优先级组装到上下文
- **独立 Writer**: 主 Agent 不直接写持久记忆，由后台 Writer 负责（Single-Writer 原则）
- **检查点系统**: 在上下文使用率达到 20%/45%/70% 时自动触发检查点，支持长任务恢复
- **记忆进化**: Dream（记忆整理）+ Distill（技能提炼），定期优化记忆质量
- **计算增强**: Max Mode（并行采样选优）、Goal Validator（完成度验证）
- **工具调用**: Agent 可调用 read_file、write_file、edit_file、grep_search、search_history 等工具
- **多模型支持**: 支持 OpenAI、Anthropic 以及任意兼容 OpenAI API 的模型（如阶跃星辰 step-3.7-flash）

## 快速开始

### 1. 安装依赖

```bash
pip install -r requirements.txt
```

> Windows 用户若遇到 `black` 安装失败，可跳过该格式化工具：`pip install -r requirements.txt --ignore-installed black`

### 2. 配置环境变量

复制环境变量模板并编辑：

```bash
cp .env.example .env
```

在 `.env` 中填入你的 API 密钥：

```env
# OpenAI 或兼容 OpenAI API 的服务商
OPENAI_API_KEY=your_api_key_here
OPENAI_BASE_URL=          # 可选：自定义 API 地址，例如 https://api.stepfun.com/v1

# Anthropic（可选）
ANTHROPIC_API_KEY=your_anthropic_api_key_here

# 默认模型
DEFAULT_MODEL=gpt-4
DEFAULT_PROVIDER=openai
```

使用阶跃星辰示例：

```env
OPENAI_API_KEY=your_stepfun_api_key
OPENAI_BASE_URL=https://api.stepfun.com/v1
DEFAULT_MODEL=step-3.7-flash
DEFAULT_PROVIDER=openai
```

### 3. 运行 Agent

```bash
python -m cli.main run "帮我分析这个项目的代码结构"

# 或使用快捷脚本
.\agent.bat run "帮我分析这个项目的代码结构"
```

### 4. 管理记忆

```bash
# 查看项目记忆
python -m cli.main memory show
.\mem-show.bat

# 添加会话笔记
python -m cli.main memory add "今天完成了登录模块"
.\mem-add.bat "今天完成了登录模块"

# 查看记忆统计
python -m cli.main memory stats
.\mem-stats.bat

# 列出会话
python -m cli.main session list
.\session-list.bat

# 保存 Trae 对话
.\save_dialog.bat "用户消息" "助手回复"
```

### 5. 运行演示（无需 API 密钥）

```bash
python demo.py
```

## 项目结构

```
ai_memo/
├── config/           # 配置层
│   ├── settings.py   # 全局配置
│   ├── prompts/      # Prompt 模板
│   └── tools/        # 工具定义 YAML
├── core/             # 核心运行时 (Phase 0)
│   ├── agent.py      # 主 Agent 循环
│   ├── llm_client.py # LLM 统一接口
│   ├── tool_executor.py   # 工具执行沙箱
│   ├── tool_loader.py     # YAML 工具加载器
│   ├── context_manager.py # 上下文 token 管理
│   └── session.py    # 会话生命周期
├── memory/           # 记忆系统 (Phase 1-3)
│   ├── layers/       # 四层记忆实现
│   │   ├── session_memory.py
│   │   ├── project_memory.py
│   │   ├── global_memory.py
│   │   └── history_store.py
│   ├── writers/      # Writer Agent
│   ├── checkpoint/   # 检查点系统
│   ├── retrieval/    # 检索系统
│   └── hierarchical_memory.py
├── evolution/        # 进化系统 (Phase 4)
│   ├── dream.py
│   ├── distill.py
│   ├── metrics.py
│   ├── scheduler.py
│   └── skill_installer.py
├── computation/      # 计算增强
│   ├── max_mode.py
│   ├── goal_validator.py
│   └── workflow/
├── cli/              # 命令行接口
│   ├── main.py
│   └── commands/
├── storage/          # 持久化存储
│   └── global/GLOBAL_MEMORY.md
├── docs/             # 项目文档
│   ├── architecture.md
│   ├── memory_layers.md
│   ├── plan0.md
│   ├── plan1.md
│   └── time_standards.md
├── examples/         # 使用示例
└── tests/            # 测试
```

## 四层记忆体系

| 层级 | 生命周期 | 存储位置 | 用途 |
|------|---------|---------|------|
| **Session** | 当前会话 | `.session_notes.md`、`.checkpoints/` | 临时状态、任务进度 |
| **Project** | 跨会话持久 | `PROJECT_MEMORY.md` | 架构决策、技术约定、常用命令 |
| **Global** | 跨项目共享 | `storage/global/GLOBAL_MEMORY.md` | 用户级偏好、编码风格 |
| **History** | 永久保存 | `history.db`（SQLite + FTS5） | 历史对话原文、全文检索 |

记忆按以下优先级注入上下文：

1. 当前任务清单
2. Session checkpoint
3. 最近 3 条用户消息
4. 项目记忆（截断到 15K tokens）
5. 全局记忆（截断到 5K tokens）
6. 下一步行动建议

详细说明见 [docs/memory_layers.md](docs/memory_layers.md)。

## 核心概念

### Single-Writer 原则

- 主 Agent 只能写入 `.session_notes.md`
- Writer Agent 负责写入 `PROJECT_MEMORY.md`、检查点和 `history.db`
- 通过权限控制避免竞态条件，保证数据一致性

### 检查点机制

- 上下文使用率达到 20% / 45% / 70% 时自动触发检查点
- Writer Agent 提取结构化信息保存到 `.checkpoints/session_*.md`
- 接近上限（85%）时重建上下文窗口，用户无感知

### 记忆进化

- **Dream**: 每周整理项目记忆，合并重复、删除过时、分类归档
- **Distill**: 每月分析历史会话，提炼可复用技能并自动安装

详细架构见 [docs/architecture.md](docs/architecture.md)。

## 演进阶段

- **Phase 0**: 基础运行时（最小可行 Agent）
- **Phase 1**: 显式记忆存储
- **Phase 2**: 独立 Writer 与检查点
- **Phase 3**: 分层记忆与检索
- **Phase 4**: 经验进化系统

完整路线图见 [docs/plan0.md](docs/plan0.md) 和 [docs/plan1.md](docs/plan1.md)。

## 时间规范

- 存储层统一使用 UTC 时间
- 展示层转换为本地时间
- 所有时间操作通过 `core/time_utils.py` 完成
- 文件名时间戳使用紧凑格式 `YYYYMMDD_HHMMSS`
- 数据库存储使用 ISO 格式 `YYYY-MM-DDTHH:MM:SS`

详见 [docs/time_standards.md](docs/time_standards.md)。

## 运行测试

```bash
pytest
```

## License

MIT