memory-pruner

自动修剪和压缩代理内存文件以防止无限增长。日志循环缓冲区、基于重要性的状态保留以及可配置的大小限制。

# Memory Pruner

Keep your agent's memory lean. Automatically prune logs, compact state files, and enforce size limits so your agent never runs out of disk or context window.

## Why This Exists

Agents accumulate memory files over time. Logs grow unbounded. State files collect stale entries. Eventually your boot-up reads 50K tokens of memory and half of it is outdated. Memory Pruner enforces limits and keeps only what matters.

## Commands

### Prune a memory file (keep last N lines)
```bash
python3 {baseDir}/scripts/memory_pruner.py prune --file ~/wake-state.md --max-lines 200
```

### Prune a log directory (circular buffer, keep last N files)
```bash
python3 {baseDir}/scripts/memory_pruner.py prune-logs --dir ~/agents/logs/ --keep 7
```

### Compact a state file (remove sections matching a pattern)
```bash
python3 {baseDir}/scripts/memory_pruner.py compact --file ~/wake-state.md --remove-before "2026-02-14"
```

### Check memory sizes
```bash
python3 {baseDir}/scripts/memory_pruner.py stats --dir ~/
```

### Dry run (show what would be pruned)
```bash
python3 {baseDir}/scripts/memory_pruner.py prune --file ~/wake-state.md --max-lines 200 --dry-run
```

## Features

- **Line-based pruning**: Keep last N lines of any file
- **Log rotation**: Circular buffer for log directories (keep last N files, delete oldest)
- **Date-based compaction**: Remove entries older than a cutoff date
- **Size limits**: Enforce max file sizes in bytes
- **Dry run mode**: Preview changes before applying
- **Stats**: Overview of memory file sizes and growth rates

---

## 中文说明

# Memory Pruner

让你的代理内存保持精简。自动修剪日志、压缩状态文件并强制执行大小限制，让你的代理永远不会耗尽磁盘空间或上下文窗口。

## 为什么需要它

代理会随着时间累积内存文件。日志无限增长。状态文件积累过时的条目。最终，你的启动过程会读取 50K token 的内存，而其中一半都已过时。Memory Pruner 强制执行限制，只保留真正重要的内容。

## 命令

### 修剪内存文件（保留最后 N 行）
```bash
python3 {baseDir}/scripts/memory_pruner.py prune --file ~/wake-state.md --max-lines 200
```

### 修剪日志目录（循环缓冲区，保留最后 N 个文件）
```bash
python3 {baseDir}/scripts/memory_pruner.py prune-logs --dir ~/agents/logs/ --keep 7
```

### 压缩状态文件（删除匹配某模式的区块）
```bash
python3 {baseDir}/scripts/memory_pruner.py compact --file ~/wake-state.md --remove-before "2026-02-14"
```

### 检查内存大小
```bash
python3 {baseDir}/scripts/memory_pruner.py stats --dir ~/
```

### 试运行（显示将被修剪的内容）
```bash
python3 {baseDir}/scripts/memory_pruner.py prune --file ~/wake-state.md --max-lines 200 --dry-run
```

## 功能特性

- **基于行的修剪**：保留任意文件的最后 N 行
- **日志轮转**：针对日志目录的循环缓冲区（保留最后 N 个文件，删除最旧的）
- **基于日期的压缩**：删除早于截止日期的条目
- **大小限制**：强制执行以字节为单位的最大文件大小
- **试运行模式**：在应用更改前预览
- **统计**：内存文件大小和增长率的概览