README.md

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

Previous versions: 0.3.x · 0.2.x · MemoryScope

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

Use Cases

• Personal assistants: Provide long-term memory for agents such as 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 has been accepted to Findings of ACL 2026.

🚀 Quick Start

Installation

ReMe requires Python 3.11+.

Install from pip:

pip install "reme-ai[core]"

Install from source:

git clone https://github.com/agentscope-ai/ReMe.git
cd ReMe
pip install -e ".[core]"

Environment Variables

Configure environment variables:

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

reme start

The default service address is 127.0.0.1:2333. If the port is occupied, specify another port:

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.

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.

Integration demos

	Auto Memory	Auto Dream
QwenPaw
Claude Code

Integration status across agents:

Agent	Status	How it integrates
QwenPaw	✅ Available	Deep SDK integration — 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	✅ 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: 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.

📁 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

<workspace_dir>/
├── metadata/       # Persistent system state such as indexes, graphs, and catalogs
├── session/        # Raw conversations and agent sessions
│   ├── dialog/
│   │   └── <session_id>.jsonl
│   ├── agentscope/
│   └── claude_code/
├── resource/            # External raw materials
│   └── YYYY-MM-DD/
│       └── <resource>.<ext>
├── daily/               # Lightly processed memory: daily facts, conversation summaries, resource readings
│   ├── YYYY-MM-DD.md
│   └── YYYY-MM-DD/
│       ├── <session_event>.md
│       ├── <resource_stem>.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

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

🤝 Community and Support

• Issues and requests: Check Open 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 and code framework, 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 for bugs and feature requests. Project documentation is available at https://reme.agentscope.io/.

Contributors

Thanks to everyone who has contributed to ReMe:

📄 Citation

@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 for details.

📈 Star History