ReMe

A local-first, self-evolving personal knowledge base for AI agents.

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

🧠 ReMe turns conversations and resources into readable, editable, searchable, and interconnected Markdown memory. It works alongside agents such as QwenPaw, OpenClaw, Hermes, and Claude Code, continuously organizing what they learn while keeping the files under the user's control.

✨ Core Ideas

• Memory as File, File as Memory: Markdown files with frontmatter and wikilinks serve as memory nodes that both users and agents can inspect, edit, move, and back up directly.
• Self-evolving knowledge base: Auto Memory, Auto Resource, and Auto Dream progressively transform conversations and resources into daily notes and long-term knowledge, while Auto Link writes relationships and sources back into the files.
• Progressive hybrid search: ReMe combines wikilinks, BM25, and embeddings for hybrid retrieval across keyword matching, optional semantic recall, and relationship expansion without loading every neighboring file into context.
• Agent-friendly integration: SKILL.md + CLI integration makes it easy for different agents to read, write, maintain, and reuse the same local workspace. HTTP, MCP, and Python integrations are also available.

🔭 Use Cases

• Personal assistants: Give personal assistants such as QwenPaw, OpenClaw, and Hermes 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.
• 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

• [2026.08] - Published the ReMe blog, an end-to-end introduction to its local-first memory architecture, self-evolving workflows, hybrid search, proactive discovery, and benchmark results.
• [2026.08] - Introduced ReMe Studio, a local web workspace for browsing, editing, and searching memory files, chatting with the read-only ReMe Agent, inspecting the digest wikilink graph, and managing the local service.
• [2026.08] - Experience-driven enhancement method of agent tool-use execution built on ReMe is available on arXiv:2608.03403.
• [2026.07] - Introduced optional Cookbooks: Daily Paper for paper discovery and analysis, and Auto Fin for researching the latest 24 hours of topic-related CLS news with local-memory search and validated historical wikilinks.
• [2026.07] - 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 when you want LLM-powered memory evolution or embedding retrieval. Embeddings are disabled by default, so the default setup does not start an embedding model or require an embedding API key.

cat > .env <<'EOF'
# Optional: used only after embedding components are explicitly enabled in the config.
# 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.

[!NOTE] To enable embedding-based semantic retrieval, uncomment components.as_embedding and components.embedding_store in reme/config/default.yaml, then change components.file_store.default.embedding_store from "" to default. See the memory search guide for details.

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.

When the web build is available, the HTTP service also serves ReMe Studio at http://127.0.0.1:2333/. Studio can browse, edit, and search the workspace, chat with the read-only workspace agent, and inspect the digest wikilink graph. Set service.web_enabled=false to disable it, or use service.web_static_dir / REME_WEB_STATIC_DIR to provide a custom static build. The Job API remains available when no web build is found.

reme version
reme health_check
reme help
curl -s http://127.0.0.1:2333/version -H 'Content-Type: application/json' -d '{}'

Use ReMe Studio

Open http://127.0.0.1:2333/ after starting the default HTTP service. Studio provides:

• Files, Daily, and Knowledge views for navigating the whole workspace or focusing on daily/ and digest/.
• Markdown tabs with preview, split editing, optimistic save checks, and local download.
• Memory Graph for exploring indexed personal, procedure, and wiki nodes and opening their Markdown sources.
• Read-only Agent chat with streamed tool activity and usage; drag a workspace file into the composer to reference it.
• Settings for service/component status, redacted effective configuration, version information, and safe index rebuilding.
• English/Chinese language switching and light, dark, or system appearance.

For frontend development, run ReMe and Studio in separate terminals:

# Terminal 1, repository root
reme start

# Terminal 2
cd website
npm install
npm run dev

Then open http://localhost:3000. The development server uses http://127.0.0.1:2333 by default; set NEXT_PUBLIC_REME_API_URL to connect to another ReMe HTTP service. Static-build and frontend configuration instructions are in the ReMe Studio guide.

5-Minute Memory Demo

With the service running, write a memory node, let ReMe index it, then retrieve it:

reme write \
  path=digest/wiki/quick-start-demo \
  name="Quick Start Demo" \
  description="A first ReMe memory node" \
  content="# Quick Start Demo

ReMe stores agent memory as readable Markdown.

Related: [[digest/wiki/memory-as-file.md]]"

reme search query="agent memory markdown" limit=5
reme read path=digest/wiki/quick-start-demo start_line=1 end_line=20

The generated file is ordinary Markdown with frontmatter:

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

📚 Usage Guides

These Markdown guides cover the main user workflows and the runtime contracts implemented by the current code.

🧑‍🍳 Cookbooks

Cookbooks are optional, end-to-end workflows assembled from ReMe jobs and steps. They are not enabled by the default configuration; select the cookbook's standalone configuration when starting ReMe. Each new cookbook will be added as another row in this table.

📁 Memory System

Memory as File, File as Memory.

ReMe treats memory as files, progressively processing filtered conversation source records and external resources from session/ and resource/ into daily/, then consolidating them into reusable long-term memory nodes under digest/. The default workspace is .reme/ under the current directory; workspace_dir=... selects a different user-owned location.

Directory Structure

<workspace_dir>/
├── metadata/       # Rebuildable indexes, graphs, catalogs, and caches
├── session/        # Conversation source records and agent sessions
│   ├── dialog/
│   │   └── <session_id>.jsonl  # Source messages saved by auto_memory
│   └── claude_code/
│       └── <session_id>.jsonl  # ReMe copy used by auto_memory_cc
├── mem_session/    # Generated agent-wrapper sessions/config, not user memory
│   ├── agentscope/
│   ├── claude_config/
│   └── codex/
├── resource/            # External raw materials
│   ├── <resource>.<ext>  # Root-level files enter today's daily layer
│   └── YYYY-MM-DD/
│       └── <resource>.<ext>
├── daily/               # Lightly processed memory: daily facts, conversation summaries, resource readings
│   ├── YYYY-MM-DD.md
│   └── YYYY-MM-DD/
│       ├── <generated_name>.md  # Topic-named conversation or resource card
│       └── interests.yaml
└── digest/              # Long-term memory: personal facts, procedural experience, knowledge nodes
    ├── personal/
    │   └── {topic/event}.md
    ├── procedure/
    │   └── {topic/event}.md
    └── wiki/
        └── {topic/event}.md

🧭 Memory Design Philosophy

Capture conversation source records 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 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. The files are the durable source of truth—indexes, graphs, catalogs, and caches under metadata/ can be rebuilt from them.

Search returns the best matching chunks with file paths and line ranges, then lists bounded incoming and outgoing wikilink neighbors by metadata. An agent can read a promising source or traverse the graph only when needed. With embeddings enabled, BM25 and vector rankings are fused with reciprocal rank fusion (RRF); otherwise the default remains BM25 plus wikilink expansion.

[!IMPORTANT] proactive only reads and exposes interest topics produced by Auto Dream. It does not independently browse the web, send notifications, or rewrite the knowledge base; the host agent decides whether and how to act on a topic.

📊 Performance

ReMe evaluates multi-session and long-context memory with agentic search-and-read workflows. The figures below are the published reference runs in this repository; model, prompt, dataset, and judging details are documented with each benchmark.

ReMe also achieved a 0.580 PROC score across five user personas in the repository's π-Bench evaluation, 2.4% above NanoBot under the same test-model configuration. PROC measures proactive handling of hidden intent, clarification, cross-session preferences and conventions, task dependencies, and underspecified requests.

🤝 Agent-friendly Integration

ReMe can run as a local memory service accessed through the CLI, HTTP API, or MCP server, or it can be embedded in the host process through its Python API. The default HTTP service can serve ReMe Studio at the same address. Agents can choose the path that fits their runtime and share a local memory workspace when appropriate.

Integration demos

	Auto Memory	Auto Dream
QwenPaw
Claude Code

🛠️ 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.

🤝 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. Source, schemas, and tests are the authoritative architecture and extension guide.
• Documentation contributions: Submit user-facing documentation changes to the unified documentation repository under reme/<version>/{en,zh}/.
• 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{ReMe2026,
  title = {Remember me, Refine me: Memory Management Kit for Agents},
  author = {ReMe Team},
  url = {https://reme.agentscope.io},
  year = {2026}
}

⚖️ License

This project is open source under the Apache License 2.0. See LICENSE for details.