scriptoriumadmin/ReMe
1
0
Fork 0
mirror of https://github.com/agentscope-ai/ReMe.git synced 2026-10-08 03:10:24 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

update the readme, reorg the content (#318)

Browse source
This commit is contained in:
Zhaoyang Liu 2026-07-03 14:56:52 +08:00 • committed by GitHub
parent 6bf2db8ff4
commit f63165c66b
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
2 changed files with 232 additions and 221 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

236
README.md
View file

@ -19,15 +19,15 @@
</p>
<p align="center">
<strong>A memory management toolkit for AI agents — Remember Me, Refine Me.</strong><br>
<strong>An agent memory layer that turns conversations and resources into readable, editable, searchable Markdown memory.</strong><br>
</p>
> Previous versions: [0.3.x](https://github.com/agentscope-ai/ReMe/tree/reme_v3) ·
> [0.2.x](https://github.com/agentscope-ai/ReMe/tree/v0.2.0.6) ·
> [MemoryScope](https://github.com/agentscope-ai/ReMe/tree/memoryscope_branch)
🧠 ReMe is a memory management toolkit for **AI agents**. It turns conversations and resources into readable, editable,
and searchable file-based long-term memory.
🧠 ReMe is a local-first memory layer for **AI agents**. It turns conversations and resources into file-based long-term
memory, then continuously indexes, links, and consolidates that memory for future recall.
## ✨ Core Ideas
@ -44,23 +44,21 @@ and searchable file-based long-term memory.
<img src="docs/figure/design-philosophy.svg" alt="ReMe Design Philosophy" width="92%">
</p>
<details>
<summary><b>Use Cases</b></summary>
## 🔭 Use Cases
<br>
- **Personal assistants**: Provide long-term memory for agents such
as [QwenPaw](https://github.com/agentscope-ai/QwenPaw).
- **Coding assistants**: Preserve coding style, project background, and workflow experience across sessions.
- **Knowledge QA**: Progressively transform resources and conversations into a searchable, traceable, and linked
Markdown knowledge base.
- **Task automation**: Reuse successful paths, lessons from failures, and operating procedures from past tasks.
</details>
- **Personal assistants**: Give personal assistants such as
[QwenPaw](https://github.com/agentscope-ai/QwenPaw), [OpenClaw](https://github.com/openclaw/openclaw), and
[Hermes](https://github.com/nousresearch/hermes-agent) a user-editable long-term memory layer.
- **Coding agents**: Preserve coding style, project background, repository decisions, and workflow
experience across sessions when integrating with coding agents such as [Claude Code](plugins/reme).
- **LLM Wiki**: Turn conversations, notes, and resources into a searchable, traceable, and linked Markdown
knowledge base that both users and agents can maintain.
- **Self-evolving agents**: Support agents that learn from experience by saving successful paths, failed attempts,
reusable procedures, and periodic reflections as memory.
## 📰 News
- Our paper [Remember Me, Refine Me: A Dynamic Procedural Memory Framework for Experience-Driven Agent Evolution](https://aclanthology.org/2026.findings-acl.829/) has been accepted to Findings of ACL 2026.
- [2026.07] - Our paper [Remember Me, Refine Me: A Dynamic Procedural Memory Framework for Experience-Driven Agent Evolution](https://aclanthology.org/2026.findings-acl.829/) has been accepted to Findings of ACL 2026.
## 🚀 Quick Start
@ -84,17 +82,22 @@ pip install -e ".[core]"
### Environment Variables
Configure environment variables:
Configure environment variables when you want LLM-powered memory evolution or embedding retrieval:
```bash
cat > .env <<'EOF'
# Optional: enables semantic retrieval when the embedding store is configured.
EMBEDDING_API_KEY=sk-xxx
EMBEDDING_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
# Required for auto_memory, auto_resource, and auto_dream.
LLM_API_KEY=sk-xxx
LLM_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
EOF
```
Basic file operations, BM25 search, wikilink traversal, and reading proactive topics can run without LLM credentials.
### Start the Service
```bash
@ -115,58 +118,46 @@ reme version
curl -s http://127.0.0.1:2333/version -H 'Content-Type: application/json' -d '{}'
```
### Agent Integration
### 5-Minute Memory Demo
ReMe runs as a service and exposes memory through CLI / MCP jobs. Agents can adopt it in whichever way fits them: deep
SDK integration, plugin integration, or a lightweight Skill + CLI integration. They can wire `auto_memory` / `proactive`
into their lifecycle so conversations are consolidated into memory and surfaced at the right time. Indexing (
`auto_index`) and resource processing (`auto_resource`) run automatically through file watching, and `auto_dream`
consolidates daily memories into long-term digests on a schedule.
With the service running, write a memory node, let ReMe index it, then retrieve it:
<p align="center"><b>Integration demos</b></p>
```bash
reme write \
path=digest/wiki/quick-start-demo \
name="Quick Start Demo" \
description="A first ReMe memory node" \
content="# Quick Start Demo
<table>
<tr>
<td align="center"></td>
<td width="45%" align="center"><b>Auto Memory</b></td>
<td width="45%" align="center"><b>Auto Dream</b></td>
</tr>
<tr>
<td align="center"><b>QwenPaw</b></td>
<td width="45%">
<img src="docs/figure/qwenpaw-auto-memory.gif" alt="QwenPaw Auto Memory demo" width="100%">
</td>
<td width="45%">
<img src="docs/figure/qwenpaw-auto-dream.gif" alt="QwenPaw Auto Dream demo" width="100%">
</td>
</tr>
<tr>
<td align="center"><b>Claude Code</b></td>
<td width="45%">
<img src="docs/figure/cc-auto-memory.gif" alt="Claude Code Auto Memory demo" width="100%">
</td>
<td width="45%">
<img src="docs/figure/cc-auto-dream.gif" alt="Claude Code Auto Dream demo" width="100%">
</td>
</tr>
</table>
ReMe stores agent memory as readable Markdown.
Integration status across agents:
Related: [[digest/wiki/memory-as-file.md]]"
| Agent | Status | How it integrates |
|-----------------------------------------------------|-------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [QwenPaw](https://github.com/agentscope-ai/QwenPaw) | ✅ Available | [Deep SDK integration](https://github.com/agentscope-ai/QwenPaw/blob/main/src/qwenpaw/agents/memory/reme_light_memory_manager.py) — embeds the ReMe app in-process, drives `search` / `auto_memory` / `auto_dream` jobs via `run_job`, and reuses the agent's own model (no separate server). |
| [Claude Code](plugins/reme) | ✅ Available | Plugin: HTTP MCP server for recall, a `reme-memory` skill, and a Stop hook that records each session via `auto_memory_cc`. |
| Skill + CLI integration | ✅ Available | [Skill + CLI](skills/reme_memory/SKILL.md): install or copy the `reme_memory` skill, then use `reme version` to check the version and `reme search query="xxx" limit=5` to search memory. |
reme search query="agent memory markdown" limit=5
reme read path=digest/wiki/quick-start-demo start_line=1 end_line=20
```
For more details, see the [Quick Start](docs/zh/quick_start.md).
The generated file is ordinary Markdown with frontmatter:
```markdown
---
name: Quick Start Demo
description: A first ReMe memory node
---
# Quick Start Demo
ReMe stores agent memory as readable Markdown.
Related: [[digest/wiki/memory-as-file.md]]
```
## 📁 Memory System
> Memory as File, File as Memory.
ReMe treats **memory as files**, progressively processing raw conversations and external resources from `session/` and
`resource/` into `daily/`, then consolidating them into reusable long-term knowledge nodes under `digest/`.
`resource/` into `daily/`, then consolidating them into reusable long-term memory nodes under `digest/`.
### Directory Structure
@ -200,20 +191,24 @@ ReMe treats **memory as files**, progressively processing raw conversations and
<img src="docs/figure/reme-overview.svg" alt="ReMe file-based memory system overview" width="92%">
</p>
## 🧭 Memory Design Philosophy
> Capture raw dialogs and resources, refine them into long-term preferences, reusable experience, and valuable knowledge,
> while keeping the result editable by humans and agents.
### Automatic Memory Flow
ReMe's automatic memory flow gradually turns raw conversations and resources into searchable, traceable, and reusable
file-based memory. During normal operation, background watchers maintain indexes and process resources, agent hooks
trigger conversation memory, and long-term consolidation plus proactive reminders run through scheduled tasks or
on-demand calls.
ReMe follows a capture → index → consolidate → recall loop. Conversations and resources first become daily memory cards;
background jobs keep files searchable; `auto_dream` distills stable knowledge into `digest/`; agents recall memory
through search, wikilinks, or proactive topics.
| Capability | How it runs | Purpose | Main parameters |
|---------------------------------------------|-----------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------|
| [`auto_index`](docs/zh/memory_search.md) | Background maintenance via `index_update_loop` | Scans on startup and continuously watches Markdown/JSONL changes in `daily/`, `digest/`, and `resource/`; updates chunk, BM25, embedding, and wikilink graph indexes. | Config: `watch_dirs`, `watch_suffixes` |
| [`auto_memory`](docs/zh/auto_memory.md) | Agent after-reply hook; also callable on demand | Saves raw conversation text and turns long-term valuable information into `daily/<date>/<session_id>.md` memory cards. | Required: `messages`; optional: `session_id`, `memory_hint` |
| [`auto_resource`](docs/zh/auto_resource.md) | Automatically triggered by resource watching; also callable on demand | Reads resource changes under `resource/<date>/` and creates or updates LLM-named daily resource cards linked by `source_resource`. | Required: `changes`; each item may include `path`, `file_path`, `change` |
| [`auto_dream`](docs/zh/auto_dream.md) | Scheduled by `dream_cron`; also callable on demand | Scans daily input for a given date, extracts long-term memory units, integrates them into `digest/`, and writes `daily/<date>/interests.yaml`. | `date`, `hint`, `topic_count`, `topic_diversity_days` |
| [`proactive`](docs/zh/proactive.md) | Read on demand before agent proactive reminders | Reads `interests.yaml` generated by `auto_dream` and exposes topics worth attention to the upper-level agent; the caller decides whether to remind the user. | `date`, `include_content` |
| Capability | Entry point | What it does | Output |
|---------------------------------------------|--------------------------------------------------|-----------------------------------------------------------------------------------------------|----------------------------------------------------------|
| [`auto_memory`](docs/en/auto_memory.md) | Agent hook or `reme auto_memory` | Distills useful conversation facts while preserving the raw session. | `session/dialog/*.jsonl`, `daily/<date>/<session>.md` |
| [`auto_resource`](docs/en/auto_resource.md) | Resource watcher or `reme auto_resource` | Turns files under `resource/<date>/` into source-linked daily cards. | `daily/<date>/<resource-card>.md` |
| [`auto_index`](docs/en/memory_search.md) | Background watcher or `reme reindex` | Maintains chunks, BM25/embedding indexes, and the wikilink graph. | Searchable `daily/`, `digest/`, and `resource/` content |
| [`auto_dream`](docs/en/auto_dream.md) | `dream_cron` or `reme auto_dream` | Consolidates changed daily cards into long-term personal, procedure, and wiki memory. | `digest/**`, `daily/<date>/interests.yaml` |
| [`proactive`](docs/en/proactive.md) | `reme proactive` before an agent decides to act | Reads topics generated by `auto_dream`; the host agent decides whether and how to mention them. | Structured topics from `daily/<date>/interests.yaml` |
<table>
<tr>
@ -234,44 +229,71 @@ on-demand calls.
</tr>
</table>
### ReMe Operations
## 🤝 Agent-friendly Integration
ReMe operates the workspace through a unified CLI / Service Job interface. Agents usually only need retrieval, reading,
writing, editing, and automatic memory commands. Lower-level indexing, frontmatter, and file operation commands are
mainly for maintenance, debugging, or advanced integration.
ReMe runs as a local memory service and offers multiple integration paths: CLI, HTTP API, MCP server, and SDK. Different
agents can choose the path that fits their runtime while sharing the same local memory workspace.
| Category | Command | Description | Parameters |
|----------------|-------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------|
| System status | `reme version` | Returns the ReMe package version. | None |
| System status | `reme health_check` | Returns a health-check summary for ReMe components. | None |
| System status | `reme help` | Lists registered jobs and their metadata. | None |
| Retrieval/read | [`reme search`](docs/zh/memory_search.md) | Performs hybrid retrieval in the workspace with vector recall, BM25, and RRF fusion. | Required: `query`; optional: `limit`, `min_score` |
| Retrieval/read | `reme node_search` | Recalls similar digest nodes by candidate abstraction name and description, mainly for `auto_dream` deduplication or association. | Required: `query`; optional: `limit` |
| Retrieval/read | `reme traverse` | Traverses the wikilink graph from a specified path. | Required: `path`; optional: `depth`, `direction` |
| Retrieval/read | `reme read` | Reads a Markdown file under the workspace. | Required: `path`; optional: `start_line`, `end_line` |
| Retrieval/read | `reme read_image` | Reads an image file under the workspace and returns base64. | Required: `path` |
| Index | `reme reindex` | Clears file-store indexes and rebuilds indexes from existing files. | Config: `watch_dirs`, `watch_suffixes` |
| Daily | `reme daily_list` | Lists notes for a day. | `date` |
| Daily | `reme daily_reindex` | Rebuilds the day-index page `daily/<date>.md`. | `date` |
| Metadata | `reme frontmatter_read` | Reads file frontmatter. | Required: `path` |
| Metadata | `reme frontmatter_update` | Merges key-values into file frontmatter. | Required: `path`, `metadata` |
| Metadata | `reme frontmatter_delete` | Deletes specified keys from file frontmatter. | Required: `path`, `keys` |
| File operation | `reme stat` | Gets workspace path status, including size, mtime, existence, and file/directory type. | Required: `path` |
| File operation | `reme list` | Lists files under a workspace path. | `path`, `recursive`, `limit` |
| File operation | `reme write` | Creates or overwrites a Markdown file and writes name/description frontmatter. | Required: `path`, `name`, `description`, `content`; optional: `metadata` |
| File operation | `reme edit` | Performs full-text find-and-replace on a Markdown file. | Required: `path`, `old`, `new` |
| File operation | `reme move` | Moves or renames a workspace file and rewrites inbound wikilinks by default. | Required: `src_path`, `dst_path`; optional: `overwrite`, `retarget` |
| File operation | `reme delete` | Deletes a workspace file or folder and returns inbound wikilinks that still exist. | Required: `path` |
| Agents | Recommended path | What works out of the box |
|------------------------------------------------------|-----------------------------------------------------------------------------|------------------------------------------------------------------------------------------------|
| **QwenPaw** | Embed ReMe via the Python SDK. | Reuse the app's own lifecycle and model config while keeping memory local and file-based. |
| **Claude Code** | Start ReMe as an MCP service and install [plugins/reme](plugins/reme). | MCP recall tools, a `reme-memory` skill, and a Stop hook that records sessions automatically. |
| **Other CLI-capable agents (OpenClaw/Hermes/Codex)** | Copy or install [skills/reme_memory/SKILL.md](skills/reme_memory/SKILL.md). | Search/read/write memory and call `auto_memory`, `auto_dream`, and `proactive` via the CLI. |
<p align="center"><b>Integration demos</b></p>
<table>
<tr>
<td align="center"></td>
<td width="45%" align="center"><b>Auto Memory</b></td>
<td width="45%" align="center"><b>Auto Dream</b></td>
</tr>
<tr>
<td align="center"><b>QwenPaw</b></td>
<td width="45%">
<img src="docs/figure/qwenpaw-auto-memory.gif" alt="QwenPaw Auto Memory demo" width="100%">
</td>
<td width="45%">
<img src="docs/figure/qwenpaw-auto-dream.gif" alt="QwenPaw Auto Dream demo" width="100%">
</td>
</tr>
<tr>
<td align="center"><b>Claude Code</b></td>
<td width="45%">
<img src="docs/figure/cc-auto-memory.gif" alt="Claude Code Auto Memory demo" width="100%">
</td>
<td width="45%">
<img src="docs/figure/cc-auto-dream.gif" alt="Claude Code Auto Dream demo" width="100%">
</td>
</tr>
</table>
## 🛠️ ReMe Operations
ReMe operates the workspace through a unified job interface exposed by the CLI. Agents usually only need retrieval,
reading, writing, editing, and automatic memory commands. Lower-level indexing, frontmatter, and file operation commands
are mainly for maintenance, debugging, or advanced integration. Run `reme help` for the full job list.
| Command | Purpose |
|-------------------------------------------|--------------------------------------------------------------------------------------|
| `reme start` | Start the local ReMe service. |
| `reme version` / `reme health_check` | Check package and component status. |
| [`reme search`](docs/en/memory_search.md) | Retrieve memory with hybrid search. |
| `reme read` / `reme write` / `reme edit` | Inspect and maintain Markdown memory files. |
| `reme auto_memory` | Turn conversation messages into daily memory cards. Requires LLM credentials. |
| `reme auto_resource` | Interpret files under `resource/` into daily resource cards. Requires LLM credentials. |
| `reme auto_dream` / `reme proactive` | Consolidate daily memory into long-term digest and surface topics worth attention. |
| `reme reindex` | Rebuild search and wikilink indexes from existing files. |
## 🤝 Community and Support
- **Issues and requests**: Check [Open Issues](https://github.com/agentscope-ai/ReMe/issues) first. If there is no
related discussion, open a new issue with background, expected behavior, and impact scope.
- **Code contributions**: Before making changes, read the [contribution guide](docs/zh/contributing.md)
and [code framework](docs/zh/framework.md), and follow the CLI / Service / Application / Job / Step / Component
- **Code contributions**: Before making changes, read the [contribution guide](docs/en/contributing.md)
and [code framework](docs/en/framework.md), and follow the CLI / Service / Application / Job / Step / Component
layering.
- **Documentation contributions**: For user-visible installation, configuration, invocation, or behavior changes, update
`docs/zh/` or `README.md` accordingly.
`docs/en/`, `docs/zh/`, or the README files accordingly.
- **Commit convention**: Conventional Commits are recommended, for example `feat(search): add link expansion option` or
`docs(zh): update quick start`.
- **Pre-submit checks**: Before submitting a PR, try to run `pre-commit run --all-files` and `pytest`. If tests that
@ -290,28 +312,12 @@ Thanks to everyone who has contributed to ReMe:
## 📄 Citation
```bibtex
@software{AgentscopeReMe2026,
title = {AgentscopeReMe: Memory Management Kit for Agents},
@software{ReMe2026,
title = {Remember me, Refine me: Memory Management Kit for Agents},
author = {ReMe Team},
url = {https://reme.agentscope.io},
year = {2026}
}
@inproceedings{cao-etal-2026-remember,
title = "Remember Me, Refine Me: A Dynamic Procedural Memory Framework for Experience-Driven Agent Evolution",
author = "Cao, Zouying and
Deng, Jiaji and
Yu, Li and
Zhou, Weikang and
Liu, Zhaoyang and
Ding, Bolin and
Zhao, Hai",
booktitle = "Findings of the {A}ssociation for {C}omputational {L}inguistics: {ACL} 2026",
year = "2026",
publisher = "Association for Computational Linguistics",
url = "https://aclanthology.org/2026.findings-acl.829/",
pages = "16803--16822"
}
```
## ⚖️ License

217
README_ZH.md
View file

@ -19,14 +19,14 @@
</p>
<p align="center">
<strong>A memory management toolkit for AI agents — Remember Me, Refine Me.</strong><br>
<strong>一个将对话和资料转化为可读、可编辑、可检索 Markdown 记忆的 Agent 记忆层。</strong><br>
</p>
> 历史版本：[0.3.x](https://github.com/agentscope-ai/ReMe/tree/reme_v3) ·
> [0.2.x](https://github.com/agentscope-ai/ReMe/tree/v0.2.0.6) ·
> [MemoryScope](https://github.com/agentscope-ai/ReMe/tree/memoryscope_branch)
🧠 ReMe 是一个面向 **AI 智能体** 的记忆管理工具，可将对话和资料沉淀为可读、可编辑、可检索的文件化长期记忆。
🧠 ReMe 是一个面向 **AI 智能体** 的 local-first 记忆层。它把对话和资料沉淀为文件化长期记忆，并持续完成索引、链接和整理，让后续 Agent 能够可靠召回。
## ✨ 核心创新
@ -39,23 +39,18 @@
<img src="docs/figure/design-philosophy.svg" alt="ReMe 设计理念" width="92%">
</p>
<details>
<summary><b>适用场景</b></summary>
## 🔭 适用场景
<br>
- **个人助理**：为 [QwenPaw](https://github.com/agentscope-ai/QwenPaw) 等 Agent 提供长期记忆。
- **编程助手**：沉淀代码风格、项目背景和流程经验，跨会话保持一致。
- **知识问答**：把资料和对话渐进加工成可检索、可追溯、可链接的 Markdown 知识库。
- **任务自动化**：复用历史任务中的成功路径、失败教训和操作流程。
</details>
- **Personal assistants**：为 [QwenPaw](https://github.com/agentscope-ai/QwenPaw)、
[OpenClaw](https://github.com/openclaw/openclaw)、[Hermes](https://github.com/nousresearch/hermes-agent)
等个人助理提供用户可编辑的长期记忆层。
- **Coding agents**：在接入 [Claude Code](plugins/reme) 等 coding agent 时，跨会话保留代码风格、项目背景、仓库决策和流程经验。
- **LLM Wiki**：把对话、笔记和资料转化为可检索、可追溯、可链接的 Markdown 知识库，由用户和 Agent 共同维护。
- **Self-evolving agents**：帮助 Agent 从经验中学习，把成功路径、失败尝试、可复用流程和阶段性反思沉淀为记忆。
## 📰 新闻
-
我们的论文 [Remember Me, Refine Me: A Dynamic Procedural Memory Framework for Experience-Driven Agent Evolution](https://aclanthology.org/2026.findings-acl.829/)
- [2026.07] - 我们的论文 [Remember Me, Refine Me: A Dynamic Procedural Memory Framework for Experience-Driven Agent Evolution](https://aclanthology.org/2026.findings-acl.829/)
已被 Findings of ACL 2026 接收。
## 🚀 快速开始
@ -80,17 +75,22 @@ pip install -e ".[core]"
### 环境变量
配置环境变量：
如果需要 LLM 驱动的记忆演化或 embedding 检索，可以配置环境变量：
```bash
cat > .env <<'EOF'
# 可选：配置 embedding store 后启用语义检索。
EMBEDDING_API_KEY=sk-xxx
EMBEDDING_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
# 必须：auto_memory、auto_resource 和 auto_dream 需要 LLM。
LLM_API_KEY=sk-xxx
LLM_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
EOF
```
基础文件读写、BM25 检索、wikilink 遍历和 proactive topics 读取可以先不配置 LLM 凭证。
### 启动服务
```bash
@ -111,49 +111,39 @@ reme version
curl -s http://127.0.0.1:2333/version -H 'Content-Type: application/json' -d '{}'
```
### 快速接入
### 5 分钟记忆 Demo
ReMe 以服务形式运行，通过 CLI / MCP job 对外暴露记忆。各 Agent 可以按适合自身的方式接入：SDK 深度集成、plugin 集成，或轻量的
Skill + CLI 集成。它们可以把 `auto_memory` / `proactive` 接入自身生命周期，让对话沉淀为记忆并在合适时机浮现。索引（
`auto_index`）与资源加工（`auto_resource`）由文件监控自动触发，`auto_dream` 则按计划把 daily 记忆整理为可长期复用的 digest。
服务运行后，可以写入一个记忆节点，让 ReMe 索引并检索它：
<p align="center"><b>集成演示</b></p>
```bash
reme write \
path=digest/wiki/quick-start-demo \
name="Quick Start Demo" \
description="第一个 ReMe 记忆节点" \
content="# Quick Start Demo
<table>
<tr>
<td align="center"></td>
<td width="45%" align="center"><b>Auto Memory</b></td>
<td width="45%" align="center"><b>Auto Dream</b></td>
</tr>
<tr>
<td align="center"><b>QwenPaw</b></td>
<td width="45%">
<img src="docs/figure/qwenpaw-auto-memory.gif" alt="QwenPaw Auto Memory 演示" width="100%">
</td>
<td width="45%">
<img src="docs/figure/qwenpaw-auto-dream.gif" alt="QwenPaw Auto Dream 演示" width="100%">
</td>
</tr>
<tr>
<td align="center"><b>Claude Code</b></td>
<td width="45%">
<img src="docs/figure/cc-auto-memory.gif" alt="Claude Code Auto Memory 演示" width="100%">
</td>
<td width="45%">
<img src="docs/figure/cc-auto-dream.gif" alt="Claude Code Auto Dream 演示" width="100%">
</td>
</tr>
</table>
ReMe 会把 Agent 记忆保存为可读的 Markdown。
各 Agent 接入状态：
相关链接：[[digest/wiki/memory-as-file.md]]"
| Agent | 状态 | 接入方式 |
|-----------------------------------------------------|-------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [QwenPaw](https://github.com/agentscope-ai/QwenPaw) | ✅ 已支持 | [SDK 深度集成](https://github.com/agentscope-ai/QwenPaw/blob/main/src/qwenpaw/agents/memory/reme_light_memory_manager.py)：进程内嵌入 ReMe 应用，通过 `run_job` 驱动 `search` / `auto_memory` / `auto_dream`，并复用 Agent 自身模型（无需独立 server）。 |
| [Claude Code](plugins/reme) | ✅ 已支持 | Plugin：通过 HTTP MCP server 做召回，提供 `reme-memory` skill，并用 Stop hook 在会话结束时经 `auto_memory_cc` 录入记忆。 |
| Skill + CLI 集成 | ✅ 已支持 | [Skill + CLI](skills/reme_memory/SKILL.md)：安装或复制 `reme_memory` skill 后，直接使用 `reme version` 检查版本，使用 `reme search query="xxx" limit=5` 检索记忆。 |
reme search query="agent memory markdown" limit=5
reme read path=digest/wiki/quick-start-demo start_line=1 end_line=20
```
更多细节见 [快速开始](docs/zh/quick_start.md)。
生成的文件是普通 Markdown，并带有 frontmatter：
```markdown
---
name: Quick Start Demo
description: 第一个 ReMe 记忆节点
---
# Quick Start Demo
ReMe 会把 Agent 记忆保存为可读的 Markdown。
相关链接：[[digest/wiki/memory-as-file.md]]
```
## 📁 记忆系统
@ -194,18 +184,22 @@ ReMe 将**记忆视为文件**，让原始对话和外部资料从 `session/`、
<img src="docs/figure/reme-overview.svg" alt="ReMe 文件化记忆系统总览" width="92%">
</p>
## 🧭 记忆设计理念
> 捕获原始对话和资料，将其整理为长期偏好、可复用经验和有价值的知识，并让结果始终能被用户和 Agent 直接编辑。
### 自动记忆流程
ReMe 的自动记忆流程会把原始对话和资料逐步加工成可检索、可追溯、可长期复用的文件化记忆。常规运行时，后台监听负责维护索引和处理资源，Agent
hook 负责触发对话记忆，长期整理与主动提醒则通过定时任务或按需调用完成。
ReMe 遵循 capture → index → consolidate → recall 的循环。对话和资料先变成 daily 记忆卡片；后台任务保持文件可检索；
`auto_dream` 将稳定知识沉淀到 `digest/`；Agent 再通过搜索、wikilink 或 proactive topics 召回记忆。
| 能力 | 运行方式 | 作用 | 主要参数 |
|---------------------------------------------|-------------------------------|---------------------------------------------------------------------------------------------------------|----------------------------------------------------|
| [`auto_index`](docs/zh/memory_search.md) | 后台维护；对应 `index_update_loop` | 启动时扫描并持续监听 `daily/`、`digest/`、`resource/` 中的 Markdown/JSONL 变化，更新 chunk、BM25、embedding 与 wikilink 图谱索引。 | 配置项：`watch_dirs`、`watch_suffixes` |
| [`auto_memory`](docs/zh/auto_memory.md) | Agent after-reply hook；也可按需调用 | 保存对话原文，并把有长期价值的信息整理成 `daily/<date>/<session_id>.md` 记忆卡片。 | 必填：`messages`；可选：`session_id`、`memory_hint` |
| [`auto_resource`](docs/zh/auto_resource.md) | 资源监听自动触发；也可按需调用 | 解读 `resource/<date>/` 下的资源变更，生成或更新由 LLM 命名、通过 `source_resource` 关联的 daily 资源卡片。 | 必填：`changes`；每项可含 `path`、`file_path`、`change` |
| [`auto_dream`](docs/zh/auto_dream.md) | 定时任务 `dream_cron`；也可按需调用 | 扫描指定日期的 daily 输入，抽取长期记忆单元并整合进 `digest/`，同时写入 `daily/<date>/interests.yaml`。 | `date`、`hint`、`topic_count`、`topic_diversity_days` |
| [`proactive`](docs/zh/proactive.md) | Agent 主动提醒前按需读取 | 读取 `auto_dream` 生成的 `interests.yaml`，将当天值得关注的主题暴露给上层 Agent；是否提醒用户由调用方决定。 | `date`、`include_content` |
| 能力 | 入口 | 作用 | 输出 |
|---------------------------------------------|-----------------------------------|-------------------------------------|----------------------------------------------------------|
| [`auto_memory`](docs/zh/auto_memory.md) | Agent hook 或 `reme auto_memory` | 提炼有长期价值的对话事实，同时保留原始 session。 | `session/dialog/*.jsonl`、`daily/<date>/<session>.md` |
| [`auto_resource`](docs/zh/auto_resource.md) | 资源监听或 `reme auto_resource` | 将 `resource/<date>/` 下的文件转为带来源链接的 daily 卡片。 | `daily/<date>/<resource-card>.md` |
| [`auto_index`](docs/zh/memory_search.md) | 后台监听或 `reme reindex` | 维护 chunks、BM25/embedding 索引和 wikilink 图谱。 | 可检索的 `daily/`、`digest/`、`resource/` 内容 |
| [`auto_dream`](docs/zh/auto_dream.md) | `dream_cron` 或 `reme auto_dream` | 将变化的 daily 卡片整理为长期 personal、procedure 和 wiki 记忆。 | `digest/**`、`daily/<date>/interests.yaml` |
| [`proactive`](docs/zh/proactive.md) | Agent 决定主动行动前调用 `reme proactive` | 读取 `auto_dream` 生成的 topics；是否以及如何提醒用户由宿主 Agent 决定。 | 来自 `daily/<date>/interests.yaml` 的结构化 topics |
<table>
<tr>
@ -226,33 +220,60 @@ hook 负责触发对话记忆，长期整理与主动提醒则通过定时任务
</tr>
</table>
### ReMe Operations
## 🤝 Agent-friendly Integration
ReMe 通过统一的 CLI / Service Job 接口操作 workspace。Agent 通常只需要使用检索、读取、写入、编辑和自动记忆相关命令；更底层的索引、frontmatter
和文件操作接口主要用于维护、调试或高级集成。
ReMe 作为本地记忆服务运行，并提供 CLI、HTTP API、MCP server 和 SDK 等多种接入方式。不同 Agent 可以选择适合自身 runtime
的路径，同时共享同一个本地 memory workspace。
| 分类 | 命令 | 描述 | 参数 |
|-------|-------------------------------------------|-----------------------------------------------------|--------------------------------------------------------|
| 系统状态 | `reme version` | 返回 ReMe 包版本。 | 无 |
| 系统状态 | `reme health_check` | 返回 ReMe 组件健康检查摘要。 | 无 |
| 系统状态 | `reme help` | 列出已注册 jobs 及其 metadata。 | 无 |
| 检索读取 | [`reme search`](docs/zh/memory_search.md) | 在 workspace 中执行混合检索，结合向量召回、BM25 和 RRF 融合。 | 必填：`query`；可选：`limit`、`min_score` |
| 检索读取 | `reme node_search` | 根据候选抽象的名称与描述召回相似 digest 节点，主要用于 `auto_dream` 去重或关联。 | 必填：`query`；可选：`limit` |
| 检索读取 | `reme traverse` | 从指定路径出发遍历 wikilink 图谱。 | 必填：`path`；可选：`depth`、`direction` |
| 检索读取 | `reme read` | 读取 workspace 下的 Markdown 文件。 | 必填：`path`；可选：`start_line`、`end_line` |
| 检索读取 | `reme read_image` | 读取 workspace 下的图片文件并返回 base64。 | 必填：`path` |
| 索引维护 | `reme reindex` | 清空文件存储索引，并基于现有文件重建索引。 | 配置项：`watch_dirs`、`watch_suffixes` |
| Daily | `reme daily_list` | 列出某一天的 notes。 | `date` |
| Daily | `reme daily_reindex` | 重建 day-index 页面 `daily/<date>.md`。 | `date` |
| 元数据 | `reme frontmatter_read` | 读取文件 frontmatter。 | 必填：`path` |
| 元数据 | `reme frontmatter_update` | 合并 key-values 到文件 frontmatter。 | 必填：`path`、`metadata` |
| 元数据 | `reme frontmatter_delete` | 删除文件 frontmatter 中的指定 keys。 | 必填：`path`、`keys` |
| 文件操作 | `reme stat` | 获取 workspace 路径状态，包括大小、mtime、是否存在、是否目录或文件。 | 必填：`path` |
| 文件操作 | `reme list` | 列出 workspace 路径下的文件。 | `path`、`recursive`、`limit` |
| 文件操作 | `reme write` | 创建或覆盖 Markdown 文件，并写入 name/description frontmatter。 | 必填：`path`、`name`、`description`、`content`；可选：`metadata` |
| 文件操作 | `reme edit` | 对 Markdown 文件执行全文 find-and-replace。 | 必填：`path`、`old`、`new` |
| 文件操作 | `reme move` | 移动或重命名 workspace 文件，并默认重写入站 wikilink。 | 必填：`src_path`、`dst_path`；可选：`overwrite`、`retarget` |
| 文件操作 | `reme delete` | 删除 workspace 文件或文件夹，并返回仍存在的入站 wikilink。 | 必填：`path` |
| Agent | 推荐接入方式 | 开箱可用能力 |
|------------------------------------------------------|-----------------------------------------------------------------------|--------------------------------------------------------------------|
| **QwenPaw** | 通过 Python SDK 嵌入 ReMe。 | 复用应用自身生命周期和模型配置，同时保持 memory 本地、文件化。 |
| **Claude Code** | 以 MCP service 启动 ReMe，并安装 [plugins/reme](plugins/reme)。 | MCP recall tools、`reme-memory` skill，以及自动记录会话的 Stop hook。 |
| **Other CLI-capable agents (OpenClaw/Hermes/Codex)** | 复制或安装 [skills/reme_memory/SKILL.md](skills/reme_memory/SKILL.md)。 | 通过 CLI 搜索/读取/写入记忆，并调用 `auto_memory`、`auto_dream` 和 `proactive`。 |
<p align="center"><b>集成演示</b></p>
<table>
<tr>
<td align="center"></td>
<td width="45%" align="center"><b>Auto Memory</b></td>
<td width="45%" align="center"><b>Auto Dream</b></td>
</tr>
<tr>
<td align="center"><b>QwenPaw</b></td>
<td width="45%">
<img src="docs/figure/qwenpaw-auto-memory.gif" alt="QwenPaw Auto Memory 演示" width="100%">
</td>
<td width="45%">
<img src="docs/figure/qwenpaw-auto-dream.gif" alt="QwenPaw Auto Dream 演示" width="100%">
</td>
</tr>
<tr>
<td align="center"><b>Claude Code</b></td>
<td width="45%">
<img src="docs/figure/cc-auto-memory.gif" alt="Claude Code Auto Memory 演示" width="100%">
</td>
<td width="45%">
<img src="docs/figure/cc-auto-dream.gif" alt="Claude Code Auto Dream 演示" width="100%">
</td>
</tr>
</table>
## 🛠️ ReMe Operations
ReMe 通过 CLI 暴露的统一 job interface 操作 workspace。Agent 通常只需要使用检索、读取、写入、编辑和自动记忆相关命令；更底层的索引、
frontmatter 和文件操作接口主要用于维护、调试或高级集成。完整 job 列表可以运行 `reme help` 查看。
| 命令 | 作用 |
|-----------------------------------------|---------------------------------------------|
| `reme start` | 启动本地 ReMe 服务。 |
| `reme version` / `reme health_check` | 检查包版本和组件状态。 |
| [`reme search`](docs/zh/memory_search.md) | 执行混合记忆检索。 |
| `reme read` / `reme write` / `reme edit` | 检查和维护 Markdown 记忆文件。 |
| `reme auto_memory` | 将对话 messages 转为 daily 记忆卡片；需要 LLM 凭证。 |
| `reme auto_resource` | 将 `resource/` 下的文件解读为 daily 资料卡片；需要 LLM 凭证。 |
| `reme auto_dream` / `reme proactive` | 将 daily 记忆整理为长期 digest，并暴露值得关注的主题。 |
| `reme reindex` | 基于已有文件重建检索和 wikilink 索引。 |
## 🤝 社区与支持
@ -260,7 +281,7 @@ ReMe 通过统一的 CLI / Service Job 接口操作 workspace。Agent 通常只
说明背景、目标行为和影响范围。
- **代码贡献**：改动前建议阅读 [贡献指南](docs/zh/contributing.md) 和 [代码框架](docs/zh/framework.md)，遵循 CLI /
Service / Application / Job / Step / Component 的分层。
- **文档贡献**：用户可见的安装、配置、调用或行为变化，请同步更新 `docs/zh/` 或 `README.md`。
- **文档贡献**：用户可见的安装、配置、调用或行为变化，请同步更新 `docs/en/`、`docs/zh/` 或 README 文件。
- **提交规范**：建议使用 Conventional Commits，例如 `feat(search): add link expansion option`、
`docs(zh): update quick start`。
- **提交前检查**：提交 PR 前请尽量运行 `pre-commit run --all-files` 和 `pytest`；如有依赖 LLM、embedding 或外部服务的测试无法运行，请在
@ -279,28 +300,12 @@ ReMe 通过统一的 CLI / Service Job 接口操作 workspace。Agent 通常只
## 📄 引用
```bibtex
@software{AgentscopeReMe2026,
title = {AgentscopeReMe: Memory Management Kit for Agents},
@software{ReMe2026,
title = {Remember me, Refine me: Memory Management Kit for Agents},
author = {ReMe Team},
url = {https://reme.agentscope.io},
year = {2026}
}
@inproceedings{cao-etal-2026-remember,
title = "Remember Me, Refine Me: A Dynamic Procedural Memory Framework for Experience-Driven Agent Evolution",
author = "Cao, Zouying and
Deng, Jiaji and
Yu, Li and
Zhou, Weikang and
Liu, Zhaoyang and
Ding, Bolin and
Zhao, Hai",
booktitle = "Findings of the {A}ssociation for {C}omputational {L}inguistics: {ACL} 2026",
year = "2026",
publisher = "Association for Computational Linguistics",
url = "https://aclanthology.org/2026.findings-acl.829/",
pages = "16803--16822"
}
```
## ⚖️ 许可证