agentscope-ai/ReMe

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

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

✨ Why ReMe?

🧠 ReMe turns conversations and resources into readable, editable, searchable, and interconnected Markdown memory. Agents such as QwenPaw, OpenClaw, Hermes, and Claude Code can share the same workspace to retrieve, maintain, and evolve knowledge, while users retain control of the durable files.

• Memory as File, File as Memory: ReMe stores durable memory as ordinary Markdown with frontmatter and wikilinks. Users and agents can inspect, edit, move, sync, and back it up with familiar tools, while indexes and generated metadata remain rebuildable.
• Self-evolving knowledge base: ReMe progressively turns conversations and resources into daily notes and long-term knowledge, preserving sources while refining facts, preferences, procedures, and relationships over time.
• Recall is precise and context-aware. BM25, optional embeddings, and wikilink expansion retrieve relevant line-level passages and their relationships without loading the entire knowledge base into the agent context.
• One memory workspace works across agents. Personal assistants, coding agents, and other agent runtimes can share the same local workspace through native integrations, SKILL.md, CLI, HTTP, MCP, or Python APIs.

📰 Latest Updates

• [2026.08] - Published @agentscope-ai/reme, providing a native ReMe memory integration for DeepSeek Harness.
• [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] - Experience-driven enhancement method of agent tool-use execution built on ReMe is available on arXiv:2608.03403.
• [2026.07] - Introduced optional plugins: 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 packages/reme_ai_studio -e ".[core]"
cd website
npm ci
npm run build:static
cd ..

The static build requires Node.js 22.13 or newer and makes Studio available from the source tree.

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

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

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

ReMe Studio (Optional)

The core installation includes Studio. After starting ReMe, open http://127.0.0.1:2333/ to browse, edit, and search the workspace. To add Studio to a base installation, use pip install "reme-ai[web]". See the ReMe Studio guide for source builds, configuration, and development.

Optional Model Configuration

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.

🤝 Use ReMe with Your Agent

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. Host integrations can add memory guidance, recall, and capture to the agent lifecycle according to the capabilities of each runtime.

Integration demos

	Auto Memory	Auto Dream
QwenPaw
Claude Code

🧠 How ReMe Works

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 digest/. The default workspace is .reme/ under the current directory; workspace_dir=... selects a different user-owned location.

Workspace Layout

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

ReMe follows a capture → index → consolidate → recall loop. Workspace files remain the durable source of truth; everything under metadata/ is rebuildable.

Search returns matching chunks with line ranges and bounded wikilink neighbors. Optional vector results are fused with BM25 through reciprocal rank fusion (RRF).

[!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.

📊 Benchmarks

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.

🧩 Extensions and Workflows

Plugins are optional Python distributions that contribute Component, Step, or Job backends and configuration. They are installed separately and enabled explicitly by configuration. Daily Paper and Auto Fin are independently packaged plugins; their source distributions live under plugins/.

See Plugin Management to install, inspect, validate, enable, and uninstall ReMe plugins.

📚 Documentation

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

🛠️ Common Commands

Run reme help for the full job list. Common workspace and maintenance commands are:

🤝 Community and Contributing

• Issues, requests, and help: Check Open Issues first. If there is no related discussion, open one with the 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.
• Documentation: Visit 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.