ReMe Logo

A memory management toolkit for AI agents — Remember Me, Refine Me.

> 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. ## ✨ Core Ideas - **Memory as File**: Markdown files with frontmatter and wikilinks serve as memory nodes that both users and agents can read and write directly. - **Self-evolving knowledge base**: Auto Memory, Auto Resource, and Auto Dream progressively transform conversations and resources into long-term memories, while automatically building wikilink relationships. - **Progressive hybrid search**: ReMe combines wikilinks, BM25, and embeddings for hybrid retrieval across keyword matching, semantic recall, and relationship expansion. - **Agent-friendly integration**: SKILL.md + CLI integration makes it easy for different agents to read, write, maintain, and reuse memory.

ReMe Design Philosophy

Use Cases

- **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.

## 📰 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. ## 🚀 Quick Start ### Installation ReMe requires Python 3.11+. Install from pip: ```bash pip install "reme-ai[core]" ``` Install from source: ```bash git clone https://github.com/agentscope-ai/ReMe.git cd ReMe pip install -e ".[core]" ``` ### Environment Variables Configure environment variables: ```bash cat > .env <<'EOF' EMBEDDING_API_KEY=sk-xxx EMBEDDING_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1 LLM_API_KEY=sk-xxx LLM_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1 EOF ``` ### Start the Service ```bash reme start ``` The default service address is `127.0.0.1:2333`. If the port is occupied, specify another port: ```bash reme start service.port=8181 # reme start workspace_dir=/tmp/reme-demo service.port=8181 ``` After startup, check the service status. If you use a custom port, replace `2333` in the URL below with that port. ```bash reme version curl -s http://127.0.0.1:2333/version -H 'Content-Type: application/json' -d '{}' ``` ### Agent Integration 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.

QwenPaw Auto Memory / Auto Dream demo

Auto Memory	Auto Dream

Integration status across agents: | 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. | For more details, see the [Quick Start](docs/zh/quick_start.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/`. ### Directory Structure ```text / ├── metadata/ # Persistent system state such as indexes, graphs, and catalogs ├── session/ # Raw conversations and agent sessions │ ├── dialog/ │ │ └── .jsonl │ ├── agentscope/ │ └── claude_code/ ├── resource/ # External raw materials │ └── YYYY-MM-DD/ │ └── . ├── daily/ # Lightly processed memory: daily facts, conversation summaries, resource readings │ ├── YYYY-MM-DD.md │ └── YYYY-MM-DD/ │ ├── .md │ ├── .md │ └── interests.yaml └── digest/ # Long-term memory: personal facts, procedural experience, knowledge nodes ├── personal/ │ └── {topic/event}.md ├── procedure/ │ └── {topic/event}.md └── wiki/ └── {topic/event}.md ```

ReMe file-based memory system overview

### 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. | 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//.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//` 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//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` |

### ReMe Operations 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. | 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/.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` | ## 🤝 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 layering. - **Documentation contributions**: For user-visible installation, configuration, invocation, or behavior changes, update `docs/zh/` or `README.md` 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 depend on LLMs, embeddings, or external services cannot run, explain that in the PR. - **Get help**: Use [GitHub Issues](https://github.com/agentscope-ai/ReMe/issues) for bugs and feature requests. Project documentation is available at [https://reme.agentscope.io/](https://reme.agentscope.io/). ### Contributors Thanks to everyone who has contributed to ReMe:

## 📄 Citation ```bibtex @software{AgentscopeReMe2026, title = {AgentscopeReMe: 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 This project is open source under the Apache License 2.0. See [LICENSE](./LICENSE) for details. ## 📈 Star History [![Star History Chart](https://api.star-history.com/svg?repos=agentscope-ai/ReMe&type=Date)](https://www.star-history.com/#agentscope-ai/ReMe&Date)