# agent-memory-skill

**Repository Path**: YyUHua/agent-memory-skill

## Basic Information

- **Project Name**: agent-memory-skill
- **Description**: 轻量级文件化记忆系统，适用于 AI Agent。无需数据库、无需外部 API、仅需 Markdown 文件。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 0
- **Created**: 2026-05-09
- **Last Updated**: 2026-05-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: 记忆, memory

## README

# 🧠 Agent Memory Skill（中文版）
自用的记忆框架，做成了开源版。对openclaw非常有效。

一个轻量级文件化记忆系统，适用于 AI Agent。

**无需数据库、无需外部 API、仅需 Markdown 文件。**

---

## 快速开始

```bash
# 1. 复制到你的项目
cp -r agent-memory-skill /your/workspace/

# 2. 设置 MEMORY_DIR 环境变量（可选，默认 ./memory/）
export MEMORY_DIR=/your/workspace/memory

# 3. 完成 — SKILL.md 会自动处理剩余逻辑
```



## 真实使用示例

假设你是一个 AI 编程助手，每次会话启动时：

```bash
# 1. 读取导航索引，了解已有记忆
cat memory/INDEX.md

# 2. 读最近两天的日志，恢复上下文
cat memory/journal/2026-05-08.md
cat memory/journal/2026-05-09.md

# 3. 需要长时记忆时，加载对应主题文件
cat memory/topics/project-config.md
```

### 记录新信息

```bash
# 自动创建今日日志并追加条目
python3 scripts/maintain.py journal

# 或者手动写
echo "## 14:30 - 修复了登录bug
Root cause: session cookie 未设置 SameSite 属性。
Fix: 在 setCookie 调用中加 sameSite:'lax'。" >> memory/journal/$(date +%Y-%m-%d).md

# 重建 INDEX 导航
python3 scripts/maintain.py index
```

### 长期记忆（主题文件）

当信息需要长期保留时（如项目配置、API 密钥说明、工作流约定），创建主题文件：

```bash
cat > memory/topics/deployment.md << 'EOF'
# 部署配置

## 服务器
- 生产: prod.example.com (SSH key)
- 测试: staging.example.com

## 命令
- 部署: ./deploy.sh prod
- 回滚: ./deploy.sh rollback
EOF

# 更新 INDEX
python3 scripts/maintain.py index
```

### 日常维护

```bash
# 查看记忆系统状态
python3 scripts/maintain.py status

# 当 INDEX 快满时，归档旧条目
python3 scripts/maintain.py archive

# 全新初始化
python3 scripts/maintain.py setup
```

### Agent 完整唤醒流程（SKILL.md）

每次会话启动时，Agent 应执行：

1. 读取 `memory/INDEX.md` — 了解记忆总览
2. 读取最近 2 天的日志 — 恢复对话连续性
3. 根据需要加载主题文件 — 获取长期知识
4. 继续正常对话

记录新信息时：
1. 追加到当日日志（带时间戳）
2. 有价值的长期信息 → 创建/更新主题文件
3. 在 INDEX.md 中添加引用

---

## 工作原理

```
memory/
├── INDEX.md         ← 导航索引：每行一条摘要，最多 200 行
├── journal/         ← 每日日志：journal/2026-05-09.md
└── topics/          ← 长期记忆：topics/project-notes.md
```

### 对大上下文 Agent（1M+）：
INDEX.md 是导航工具，不是容量限制。
用于快速定位重要信息，再读取完整文件。

### 对小上下文 Agent：
INDEX.md 配合截断保护，保持记忆可控。

## 功能

- **日志自动写入** — 按日期分文件，带时间戳
- **INDEX.md 导航** — 单行摘要，自动截断
- **主题记忆** — 按主题分文件存储
- **唤醒流程** — INDEX → 最近 2 天日志 → 继续对话
- **可配置限制** — 行数、字节数、路径均可自定义

## 致谢

灵感来自 Claude Code 的 memdir 系统。
作者：[YyUHua](https://gitee.com/YyUHua)

## 开源协议

MIT

---

# 🧠 Agent Memory Skill (English)

A lightweight, file-based memory system for AI agents.

**No database. No external API. Just markdown files.**

## Quick Start

```bash
# 1. Copy to your project
cp -r agent-memory-skill /your/workspace/

# 2. Set MEMORY_DIR env var (optional, defaults to ./memory/)
export MEMORY_DIR=/your/workspace/memory

# 3. Done — the SKILL.md handles the rest
```

## How It Works

```
memory/
├── INDEX.md         ← Navigation: one line per entry, max 200 lines
├── journal/         ← Daily journals: journal/2026-05-09.md
└── topics/          ← Durable memories: topics/project-notes.md
```

### For agents with large context windows (1M+):
INDEX.md is a navigation aid, not a size constraint.
Use it to quickly find what matters, then read the full file.

### For agents with small context windows:
INDEX.md plus truncation protection keeps memory manageable.

## Features

- **Journal auto-write** — daily files with timestamps
- **INDEX.md navigation** — one-line summaries, auto-truncation
- **Topic-based memory** — separate files for distinct subjects
- **Wake-up flow** — INDEX → last 2 journals → continue
- **Configurable limits** — lines, bytes, paths

## Credits

Inspired by Claude Code's memdir system.
Built by [YyUHua](https://gitee.com/YyUHua).

## License

MIT