From a457bf7542e92d52554ea9e0a59960a6b0b7e369 Mon Sep 17 00:00:00 2001 From: jinliyl <6469360+jinliyl@users.noreply.github.com> Date: Wed, 26 Aug 2026 19:30:16 +0800 Subject: [PATCH] docs: reorganize readme around agent integrations (#492) --- README.md | 268 ++++++++++++++++++++++++--------------------------- README_ZH.md | 245 ++++++++++++++++++++++------------------------ 2 files changed, 241 insertions(+), 272 deletions(-) diff --git a/README.md b/README.md index 543b461d..29b206b1 100644 --- a/README.md +++ b/README.md @@ -27,39 +27,27 @@ > [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 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. +## ✨ Why ReMe? -## ✨ Core Ideas +🧠 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**: 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. +- **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.

ReMe Design Philosophy

-## 🔭 Use Cases - -- **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](integrations/claude_code/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 +## 📰 Latest Updates - [2026.08] - Published [`@agentscope-ai/reme`](https://www.npmjs.com/package/@agentscope-ai/reme), providing a native ReMe memory integration for DeepSeek Harness. @@ -100,42 +88,6 @@ cd .. The static build requires Node.js 22.13 or newer and makes Studio available from the source tree. -### DeepSeek Harness Integration - -With the ReMe service running, install the npm package into the DeepSeek Harness Web profile: - -```bash -dsh plugin --profile web add @agentscope-ai/reme -``` - -The plugin recalls relevant ReMe memory before agent steps and submits completed main-agent turns for automatic memory -capture. See the [TypeScript integration guide](packages/typescript/README.md#deepseek-harness) for configuration. - -### 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. - -```bash -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`](reme/config/default.yaml), then change -> `components.file_store.default.embedding_store` from `""` to `default`. See the -> [memory search guide](docs/en/memory_search.md) for details. - ### Start the Service ```bash @@ -156,12 +108,6 @@ reme help curl -s http://127.0.0.1:2333/version -H 'Content-Type: application/json' -d '{}' ``` -### ReMe Studio (Optional) - -The `core` installation above includes Studio. After starting ReMe, open 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](https://reme.agentscope.io/?doc=studio-en) for source builds, configuration, and development. - ### 5-Minute Memory Demo With the service running, write a memory node, let ReMe index it, then retrieve it: @@ -196,36 +142,81 @@ ReMe stores agent memory as readable Markdown. Related: [[digest/wiki/memory-as-file.md]] ``` -## 📚 Usage Guides +### ReMe Studio (Optional) -These Markdown guides cover the main user workflows and the runtime contracts implemented by the current code. +The `core` installation includes Studio. After starting ReMe, open 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](https://reme.agentscope.io/?doc=studio-en) for source builds, configuration, and development. -| Guide | What you will learn | -|-------|---------------------| -| [Quick Start](docs/en/quick_start.md) | Install ReMe, start the service, and run the first file and memory operations. | -| [Plugin Management](docs/en/plugin_management.md) | Install, inspect, validate, enable, and uninstall local ReMe plugins. | -| [Memory as File](docs/en/memory_as_file.md) | Understand workspace layers, frontmatter, wikilinks, chunks, and the file-as-source-of-truth model. | -| [Auto Memory](docs/en/auto_memory.md) | Preserve source conversations and distill reusable daily memory cards. | -| [Auto Resource](docs/en/auto_resource.md) | Import supported text resources and turn them into source-linked daily cards. | -| [Auto Dream](docs/en/auto_dream.md) and [Auto Link](docs/en/auto_link.md) | Consolidate daily notes into evolving digest nodes and readable wikilink relationships. | -| [Memory Search](docs/en/memory_search.md) | Use BM25, optional vectors, RRF fusion, line-range recall, and progressive link expansion. | -| [Proactive](docs/en/proactive.md) | Read interest topics safely and integrate them into a host agent's decision flow. | -| [Agent Integration Scenarios](docs/en/reme_scene.md) | Choose among CLI/SKILL.md, HTTP, MCP, and embedded Python integration. | -| [Framework](docs/en/framework.md) | Understand Application, Job, Step, Component, service, configuration, and lifecycle boundaries. | -| [ReMe Blog](https://agentscope-ai.github.io/ReMe/?doc=en-reme-blog) | Read the product story, design rationale, examples, and benchmark summary. | +### Optional Model Configuration -## 🔌 Plugins +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. -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/`](plugins/README.md). +```bash +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 -| Plugin | Capability | -|-----------------------------------------------|---------------------------------------------------------------------------------------------------------------| -| [Daily Paper](https://reme.agentscope.io/?doc=daily-paper-en) | Discover and rank papers, analyze PDFs with an agent, and generate file-native notes and a five-minute brief. | -| [Auto Fin](https://reme.agentscope.io/?doc=auto-fin-en) | Fetch topic-related CLS news, search ReMe history, and generate wikilink-backed Markdown reports. | +# 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 +``` -## 📁 Memory System +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`](reme/config/default.yaml), then change +> `components.file_store.default.embedding_store` from `""` to `default`. See the +> [memory search guide](docs/en/memory_search.md) 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. + +| Agent | Recommended path | Available after integration | +| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | +| **DeepSeek Harness** | Install [`@agentscope-ai/reme`](packages/typescript/README.md#deepseek-harness) with `dsh plugin --profile web add @agentscope-ai/reme`. | Long-term memory guidance, the `reme_search` tool, and automatic capture of completed main-agent turns. | +| **OpenClaw** | Install [`@agentscope-ai/reme`](packages/typescript/README.md#openclaw) with `openclaw plugins install @agentscope-ai/reme`. | Native memory tools, recall before user-triggered runs, and automatic turn capture. | +| **QwenPaw** | Embed ReMe in-process through its Python API. | Reuse the host lifecycle and model config while keeping memory local and file-based. | +| **Claude Code** | Start the streamable HTTP MCP service and install [the ReMe plugin](integrations/claude_code/reme). | MCP recall tools, the `reme-memory` skill, and a Stop hook that records sessions automatically. | +| **Hermes** | Start the HTTP service and install [the ReMe provider](integrations/hermes_agent). | Recall before model calls and asynchronous `auto_memory` after each completed turn. | +| **Codex and other CLI agents** | Install or copy the [ReMe Memory skill](skills/reme_memory/SKILL.md). | Search, read, and write memory through the CLI; automatic capture requires host lifecycle integration. | + +

Integration demos

+ + + + + + + + + + + + + + + + + +
Auto MemoryAuto Dream
QwenPaw + QwenPaw Auto Memory demo + + QwenPaw Auto Dream demo +
Claude Code + Claude Code Auto Memory demo + + Claude Code Auto Dream demo +
+ +## 🧠 How ReMe Works > Memory as File, File as Memory. @@ -233,7 +224,7 @@ ReMe treats **memory as files**, progressively processing filtered conversation 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. -### Directory Structure +### Workspace Layout ```text / @@ -269,13 +260,13 @@ directory; `workspace_dir=...` selects a different user-owned location. ReMe file-based memory system overview

-## 🧭 Memory Design Philosophy +### Memory Lifecycle ReMe follows a capture → index → consolidate → recall loop. Workspace files remain the durable source of truth; everything under `metadata/` is rebuildable. | 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 a filtered conversation source record. | `session/dialog/*.jsonl`, `daily//.md` | | [`auto_resource`](docs/en/auto_resource.md) | Resource watcher or `reme auto_resource` | Turns files under `resource/` into source-linked, content-named daily cards. | `daily//.md` | | [`auto_index`](docs/en/memory_search.md) | Background watcher or `reme reindex` | Live-indexes Markdown in `daily/` and `digest/`; a full rebuild also scans `resource/` and JSONL. | Searchable chunks, BM25, wikilink graph, and optional vectors | @@ -305,17 +296,18 @@ Search returns matching chunks with line ranges and bounded wikilink neighbors. 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. -## 📊 Performance +## 📊 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. -| Benchmark | Setting | Sample size | Agentic score | Focus | -|--------------------------------------------------------------|--------------|-------------------------:|--------------:|--------------------------------------------------------------------| +| Benchmark | Setting | Sample size | Agentic score | Focus | +| --------------------------------------------------------------------------- | ------------ | -----------------------: | ------------: | ------------------------------------------------------------------ | | **[LongMemEval cleaned-s](https://reme.agentscope.io/?doc=longmemeval-en)** | **Overall** | **500 questions** | **89.4%** | Cross-session retrieval, knowledge updates, and temporal reasoning | | [BEAM](https://reme.agentscope.io/?doc=beam-en) | 100K context | 20 cases / 400 questions | 66.1% | Ten types of long-context memory tasks | | [BEAM](https://reme.agentscope.io/?doc=beam-en) | 1M context | 35 cases / 700 questions | 65.0% | Ultra-long conversation settings | @@ -325,60 +317,50 @@ ReMe also achieved a **0.580 PROC score across five user personas** in the repos measures proactive handling of hidden intent, clarification, cross-session preferences and conventions, task dependencies, and underspecified requests. -## 🤝 Agent-friendly Integration +## 🧩 Extensions and Workflows -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. +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/`](plugins/README.md). -| Agents | Recommended path | Available after integration | -|-----------------------------------------------|---------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------| -| **QwenPaw** | Embed ReMe in-process through its Python API. | Reuse the host application's lifecycle and model config while keeping memory local and file-based. | -| **Claude Code** | Start the streamable HTTP MCP service and install [integrations/claude_code/reme](integrations/claude_code/reme). | MCP recall tools, a `reme-memory` skill, and a Stop hook that records sessions automatically. | -| **Hermes** | Start the HTTP service and install [integrations/hermes_agent](integrations/hermes_agent). | Recall relevant memory before model calls and enqueue `auto_memory` after each completed turn. | -| **Other CLI-capable agents (OpenClaw/Codex)** | Copy or install [skills/reme_memory/SKILL.md](skills/reme_memory/SKILL.md). | Search, read, and write memory via the CLI; automatic recording requires explicit host lifecycle hooks. | +| Plugin | Capability | +| ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | +| [Daily Paper](https://reme.agentscope.io/?doc=daily-paper-en) | Discover and rank papers, analyze PDFs with an agent, and generate file-native notes and a five-minute brief. | +| [Auto Fin](https://reme.agentscope.io/?doc=auto-fin-en) | Fetch topic-related CLS news, search ReMe history, and generate wikilink-backed Markdown reports. | -

Integration demos

+See [Plugin Management](docs/en/plugin_management.md) to install, inspect, validate, enable, and uninstall ReMe plugins. - - - - - - - - - - - - - - - - -
Auto MemoryAuto Dream
QwenPaw - QwenPaw Auto Memory demo - - QwenPaw Auto Dream demo -
Claude Code - Claude Code Auto Memory demo - - Claude Code Auto Dream demo -
+## 📚 Documentation -## 🛠️ ReMe Operations +These guides cover the main user workflows and the runtime contracts implemented by the current code. + +| Guide | What you will learn | +| ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | +| [Quick Start](docs/en/quick_start.md) | Install ReMe, start the service, and run the first file and memory operations. | +| [Memory as File](docs/en/memory_as_file.md) | Understand workspace layers, frontmatter, wikilinks, chunks, and the file-as-source-of-truth model. | +| [Auto Memory](docs/en/auto_memory.md) | Preserve source conversations and distill reusable daily memory cards. | +| [Auto Resource](docs/en/auto_resource.md) | Import supported text resources and turn them into source-linked daily cards. | +| [Auto Dream](docs/en/auto_dream.md) and [Auto Link](docs/en/auto_link.md) | Consolidate daily notes into evolving digest nodes and readable wikilink relationships. | +| [Memory Search](docs/en/memory_search.md) | Use BM25, optional vectors, RRF fusion, line-range recall, and progressive link expansion. | +| [Proactive](docs/en/proactive.md) | Read interest topics safely and integrate them into a host agent's decision flow. | +| [Agent Integration Scenarios](docs/en/reme_scene.md) | Choose among CLI/SKILL.md, HTTP, MCP, and embedded Python integration. | +| [Framework](docs/en/framework.md) | Understand Application, Job, Step, Component, service, configuration, and lifecycle boundaries. | +| [ReMe Blog](https://agentscope-ai.github.io/ReMe/?doc=en-reme-blog) | Read the product story, design rationale, examples, and benchmark summary. | + +## 🛠️ Common Commands Run `reme help` for the full job list. Common workspace and maintenance commands are: -| Command | Purpose | -|-------------------------------------------|----------------------------------------------------------------------------------------| -| `reme status` | Show stateful data-component memory estimates and process RSS. | -| [`reme search`](docs/en/memory_search.md) | Retrieve memory with BM25 and wikilinks by default, plus vectors when enabled. | -| `reme read` / `reme write` / `reme edit` | Inspect and maintain Markdown memory files. | -| `reme traverse` / `reme graph_snapshot` | Explore wikilink neighborhoods or the category-rooted digest graph. | -| `reme chat` | Stream a read-only, workspace-aware agent conversation. Requires LLM credentials. | -| `reme reindex` | Rebuild search and wikilink indexes from existing files. | +| Command | Purpose | +| ----------------------------------------- | --------------------------------------------------------------------------------- | +| `reme status` | Show stateful data-component memory estimates and process RSS. | +| [`reme search`](docs/en/memory_search.md) | Retrieve memory with BM25 and wikilinks by default, plus vectors when enabled. | +| `reme read` / `reme write` / `reme edit` | Inspect and maintain Markdown memory files. | +| `reme traverse` / `reme graph_snapshot` | Explore wikilink neighborhoods or the category-rooted digest graph. | +| `reme chat` | Stream a read-only, workspace-aware agent conversation. Requires LLM credentials. | +| `reme reindex` | Rebuild search and wikilink indexes from existing files. | -## 🤝 Community and Support +## 🤝 Community and Contributing - **Issues, requests, and help**: Check [Open Issues](https://github.com/agentscope-ai/ReMe/issues) first. If there is no related discussion, open one with the background, expected behavior, and impact scope. diff --git a/README_ZH.md b/README_ZH.md index 77002eaa..c9218c4e 100644 --- a/README_ZH.md +++ b/README_ZH.md @@ -27,31 +27,25 @@ > [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 将对话和资料持续沉淀为可读、可编辑、可检索、相互链接的 Markdown 记忆。它可以与 QwenPaw、OpenClaw、Hermes 和 Claude -Code 等 Agent 协作，在持续整理知识的同时，始终把文件控制权留给用户。 +## ✨ 为什么选择 ReMe？ -## ✨ 核心创新 +🧠 ReMe 将对话和资料持续沉淀为可读、可编辑、可检索、相互链接的 Markdown 记忆。QwenPaw、OpenClaw、Hermes 和 +Claude Code 等 Agent 可以共享同一个 workspace，共同检索、维护和演化知识，而持久文件始终由用户掌控。 -- **Memory as File, File as Memory**：以带 frontmatter 和 wikilink 的 Markdown 作为记忆节点，用户和 Agent 都能直接查看、编辑、移动和备份。 -- **自进化知识库**：Auto Memory、Auto Resource 和 Auto Dream 把对话与资料逐步加工为 daily 记忆和长期知识，Auto Link - 再将关系与来源写回文件。 -- **渐进式混合搜索**：融合 wikilink、BM25 和可选 embedding，从关键词匹配、语义召回到关系扩展，避免一次性将所有邻居全文塞入上下文。 -- **Agent 友好集成**：可通过 SKILL.md + CLI 读写和维护同一个本地 workspace，也支持 HTTP、MCP 和 Python API 接入。 +- **Memory as File, File as Memory**：ReMe 使用带 frontmatter 和 wikilink 的普通 Markdown 保存持久记忆。用户和 Agent + 都可以使用熟悉的工具查看、编辑、移动、同步和备份；索引及生成的元数据均可重建。 +- **自进化知识库**：ReMe 将对话和资料逐步加工为 daily note 与长期知识，在保留来源的同时，持续提炼事实、偏好、 + 流程经验及其关系。 +- **精准召回所需上下文。** ReMe 结合 BM25、可选 embedding 和 wikilink 展开，召回带行号的相关片段及其关系，无需把整个知识库塞入 + Agent 上下文。 +- **一个 workspace，可供不同 Agent 共同使用。** 个人助理、coding agent 和其他 Agent runtime 可以通过原生集成、SKILL.md、CLI、 + HTTP、MCP 或 Python API 共享同一个本地记忆空间。

ReMe 设计理念

-## 🔭 适用场景 - -- **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](integrations/claude_code/reme) 等 coding agent 时，跨会话保留代码风格、项目背景、仓库决策和流程经验。 -- **LLM Wiki**：把对话、笔记和资料转化为可检索、可追溯、可链接的 Markdown 知识库，由用户和 Agent 共同维护。 -- **Self-evolving agents**：帮助 Agent 从经验中学习，把成功路径、失败尝试、可复用流程和阶段性反思沉淀为记忆。 - -## 📰 新闻 +## 📰 最新动态 - [2026.08] - 发布 [`@agentscope-ai/reme`](https://www.npmjs.com/package/@agentscope-ai/reme)，为 DeepSeek Harness 提供原生 ReMe 记忆集成。 @@ -93,42 +87,6 @@ cd .. 静态构建要求 Node.js 22.13 或更高版本，并让源码安装可以直接使用 Studio。 -### DeepSeek Harness 集成 - -启动 ReMe 服务后，将 npm 包安装到 DeepSeek Harness 的 Web profile： - -```bash -dsh plugin --profile web add @agentscope-ai/reme -``` - -插件会在 Agent step 前检索相关 ReMe 记忆，并将主 Agent 已完成的对话提交给自动记忆任务。配置方法见 -[TypeScript 集成指南](packages/typescript/README_ZH.md#deepseek-harness)。 - -### 环境变量 - -如果需要 LLM 驱动的记忆演化或 embedding 检索，可以配置环境变量。embedding 默认关闭，因此默认配置不会启动 embedding 模型，也不需要 -embedding API key。 - -```bash -cat > .env <<'EOF' -# 可选：仅在配置中显式启用 embedding 组件后使用。 -# 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 凭证。 - -> [!NOTE] -> 如需启用基于 embedding 的语义检索，请取消 [`reme/config/default.yaml`](reme/config/default.yaml) 中 -> `components.as_embedding` 和 `components.embedding_store` 的注释，并将 -> `components.file_store.default.embedding_store` 从 `""` 改为 `default`。完整说明见 -> [记忆检索文档](docs/zh/memory_search.md)。 - ### 启动服务 ```bash @@ -149,12 +107,6 @@ reme help curl -s http://127.0.0.1:2333/version -H 'Content-Type: application/json' -d '{}' ``` -### ReMe Studio（可选） - -上面的 `core` 安装已包含 Studio。启动 ReMe 后，打开 即可浏览、编辑和搜索 workspace。 -如需为基础安装单独添加 Studio，可使用 `pip install "reme-ai[web]"`。源码构建、配置和开发说明见 -[ReMe Studio 指南](https://reme.agentscope.io/?doc=studio-zh)。 - ### 5 分钟记忆 Demo 服务运行后，可以写入一个记忆节点，让 ReMe 索引并检索它： @@ -189,42 +141,87 @@ ReMe 会把 Agent 记忆保存为可读的 Markdown。 相关链接：[[digest/wiki/memory-as-file.md]] ``` -## 📚 使用指南 +### ReMe Studio（可选） -下列 Markdown 文档覆盖主要使用流程，并以当前代码的运行时契约为准。 +上面的 `core` 安装已包含 Studio。启动 ReMe 后，打开 即可浏览、编辑和搜索 workspace。 +如需为基础安装单独添加 Studio，可使用 `pip install "reme-ai[web]"`。源码构建、配置和开发说明见 +[ReMe Studio 指南](https://reme.agentscope.io/?doc=studio-zh)。 -| 文档 | 主要内容 | -|------|----------| -| [快速开始](docs/zh/quick_start.md) | 安装 ReMe、启动服务，并执行首次文件和记忆操作。 | -| [插件管理](docs/zh/plugin_management.md) | 安装、查看、校验、启用和卸载本地 ReMe 插件。 | -| [Memory as File](docs/zh/memory_as_file.md) | 理解 workspace 分层、frontmatter、wikilink、chunk 和文件事实来源模型。 | -| [Auto Memory](docs/zh/auto_memory.md) | 保留过滤后的对话来源记录，并提炼可复用的 daily 记忆卡片。 | -| [Auto Resource](docs/zh/auto_resource.md) | 导入支持的文本资料，转换为可追溯来源的 daily 卡片。 | -| [Auto Dream](docs/zh/auto_dream.md) 与 [Auto Link](docs/zh/auto_link.md) | 将 daily 记忆整理为持续演化的 digest 节点和可读 wikilink 关系。 | -| [记忆检索](docs/zh/memory_search.md) | 使用 BM25、可选向量、RRF 融合、行号范围召回和渐进式链接扩展。 | -| [Proactive](docs/zh/proactive.md) | 安全读取兴趣主题，并将其接入宿主 Agent 的决策流程。 | -| [Agent 接入场景](docs/zh/reme_scene.md) | 在 CLI/SKILL.md、HTTP、MCP 和嵌入式 Python 集成之间选择。 | -| [框架说明](docs/zh/framework.md) | 理解 Application、Job、Step、Component、service、配置和生命周期边界。 | -| [ReMe 博客](https://agentscope-ai.github.io/ReMe/?doc=zh-reme-blog) | 了解完整产品故事、设计动机、使用示例和评测摘要。 | +### 可选模型配置 -## 🔌 插件 +如果需要 LLM 驱动的记忆演化或 embedding 检索，可以配置环境变量。embedding 默认关闭，因此默认配置不会启动 embedding 模型，也不需要 +embedding API key。 -插件是可选的独立 Python distribution，可以贡献 Component、Step、Job backend 和配置，并通过配置显式启用。每日论文与 Auto Fin -均已独立打包，源码 distribution 位于 [`plugins/`](plugins/README.md)。 +```bash +cat > .env <<'EOF' +# 可选：仅在配置中显式启用 embedding 组件后使用。 +# EMBEDDING_API_KEY=sk-xxx +# EMBEDDING_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1 -| 插件 | 能力 | -|-----------------------------------------------|--------------------------------------------------------------------------------| -| [每日论文](https://reme.agentscope.io/?doc=daily-paper-zh) | 发现并排序论文，使用 Agent 解读 PDF，生成文件化论文笔记和五分钟简报。 | -| [Auto Fin](https://reme.agentscope.io/?doc=auto-fin-zh) | 拉取主题相关财联社新闻，搜索 ReMe 历史材料并生成带 wikilink 的 Markdown 报告。 | +# 必须：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 凭证。 + +> [!NOTE] +> 如需启用基于 embedding 的语义检索，请取消 [`reme/config/default.yaml`](reme/config/default.yaml) 中 +> `components.as_embedding` 和 `components.embedding_store` 的注释，并将 +> `components.file_store.default.embedding_store` 从 `""` 改为 `default`。完整说明见 +> [记忆检索文档](docs/zh/memory_search.md)。 + +## 🤝 将 ReMe 接入你的 Agent + +ReMe 既可以作为本地记忆服务，通过 CLI、HTTP API 或 MCP server 接入，也可以通过 Python API 嵌入宿主进程。宿主集成可根据不同 +runtime 的能力，将记忆指引、召回和捕获接入 Agent 生命周期。 + +| Agent | 推荐接入方式 | 接入后能力 | +| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | +| **DeepSeek Harness** | 使用 `dsh plugin --profile web add @agentscope-ai/reme` 安装 [`@agentscope-ai/reme`](packages/typescript/README_ZH.md#deepseek-harness)。 | 长期记忆指引、`reme_search` 工具，以及自动捕获已完成的主 Agent 对话。 | +| **OpenClaw** | 使用 `openclaw plugins install @agentscope-ai/reme` 安装 [`@agentscope-ai/reme`](packages/typescript/README_ZH.md#openclaw)。 | 原生记忆工具、用户触发运行前召回和自动对话捕获。 | +| **QwenPaw** | 通过 Python API 在进程内嵌入 ReMe。 | 复用宿主生命周期和模型配置，同时保持记忆本地、文件化。 | +| **Claude Code** | 启动 streamable HTTP MCP service，并安装 [ReMe 插件](integrations/claude_code/reme)。 | MCP 召回工具、`reme-memory` skill，以及自动记录会话的 Stop hook。 | +| **Hermes** | 启动 HTTP service，并安装 [ReMe provider](integrations/hermes_agent)。 | 模型调用前召回，每轮对话完成后异步执行 `auto_memory`。 | +| **Codex 及其他 CLI Agent** | 安装或复制 [ReMe Memory skill](skills/reme_memory/SKILL.md)。 | 通过 CLI 搜索、读取和写入记忆；自动捕获需要显式接入宿主生命周期。 | + +

集成演示

+ + + + + + + + + + + + + + + + + +
Auto MemoryAuto Dream
QwenPaw + QwenPaw Auto Memory 演示 + + QwenPaw Auto Dream 演示 +
Claude Code + Claude Code Auto Memory 演示 + + Claude Code Auto Dream 演示 +
+ +## 🧠 ReMe 如何工作 > Memory as File, File as Memory. ReMe 将 **记忆视为文件**，让过滤后的对话来源记录和外部资料从 `session/`、`resource/` 渐进加工到 `daily/`，再沉淀为 `digest/`。默认 workspace 是当前目录下的 `.reme/`；可通过 `workspace_dir=...` 选择其他由用户控制的位置。 -### 目录结构 +### Workspace 结构 ```text / @@ -260,13 +257,13 @@ ReMe 将 **记忆视为文件**，让过滤后的对话来源记录和外部资 ReMe 文件化记忆系统总览

-## 🧭 记忆设计理念 +### 记忆生命周期 ReMe 遵循 capture → index → consolidate → recall 的循环。workspace 文件是持久化的事实来源，`metadata/` 中的内容均可重建。 | 能力 | 入口 | 作用 | 输出 | -|---------------------------------------------|-------------------------------------------|----------------------------------------------------------------------------------------------|--------------------------------------------------------------| -| [`auto_memory`](docs/zh/auto_memory.md) | Agent hook 或 `reme auto_memory` | 提炼有长期价值的对话事实，同时保留过滤后的对话来源记录。 | `session/dialog/*.jsonl`、`daily//.md` | +| ------------------------------------------- | ----------------------------------------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | +| [`auto_memory`](docs/zh/auto_memory.md) | Agent hook 或 `reme auto_memory` | 提炼有长期价值的对话事实，同时保留过滤后的对话来源记录。 | `session/dialog/*.jsonl`、`daily//.md` | | [`auto_resource`](docs/zh/auto_resource.md) | 资源监听或 `reme auto_resource` | 将 `resource/` 下的文件转为带来源链接、按内容命名的 daily 卡片。 | `daily//.md` | | [`auto_index`](docs/zh/memory_search.md) | 后台监听或 `reme reindex` | 实时索引 `daily/` 和 `digest/` 中的 Markdown；全量重建还会扫描 `resource/` 和 JSONL。 | 可检索的 chunks、BM25、wikilink 图谱和可选向量 | | [`auto_dream`](docs/zh/auto_dream.md) | `dream_cron` 或 `reme auto_dream` | 默认从最近两天内变化的文件中最多提取 5 个可复用 unit，再创建、印证、补充或修正 digest 节点。 | `digest/**`、`daily//interests.yaml` | @@ -294,15 +291,16 @@ ReMe 遵循 capture → index → consolidate → recall 的循环。workspace 搜索返回带行号范围的相关 chunks 和数量受限的 wikilink 邻居；可选向量结果通过 RRF 与 BM25 融合。 > [!IMPORTANT] +> > `proactive` 只读取并暴露 Auto Dream 生成的兴趣主题，不会自行联网、发送通知或改写知识库；是否以及如何使用主题，由宿主 Agent -决定。 +> 决定。 -## 📊 性能表现 +## 📊 评测结果 ReMe 通过 Agent 多轮搜索与读取的方式，评测多会话和超长上下文中的记忆能力。下表为仓库中已公开的参考实验结果；模型、prompt、数据集和评判细节见各评测文档。 -| 基准 | 设置 | 样本量 | Agentic 得分 | 主要检验内容 | -|-----------------------------------------------------------------|-------------|------------------:|-------------:|--------------------------------| +| 基准 | 设置 | 样本量 | Agentic 得分 | 主要检验内容 | +| --------------------------------------------------------------------------- | ----------- | ----------------: | -----------: | ------------------------------ | | **[LongMemEval cleaned-s](https://reme.agentscope.io/?doc=longmemeval-zh)** | **整体** | **500 题** | **89.4%** | 跨会话检索、知识更新与时间推理 | | [BEAM](https://reme.agentscope.io/?doc=beam-zh) | 100K 上下文 | 20 cases / 400 题 | 66.1% | 十类长上下文记忆任务 | | [BEAM](https://reme.agentscope.io/?doc=beam-zh) | 1M 上下文 | 35 cases / 700 题 | 65.0% | 超长对话设置 | @@ -310,52 +308,41 @@ ReMe 通过 Agent 多轮搜索与读取的方式，评测多会话和超长上 在仓库的 [π-Bench 评测](https://reme.agentscope.io/?doc=pibench-zh)中，ReMe Agent 在 5 种用户角色上的平均 **PROC 得分为 0.580** ，比相同测试模型配置的 NanoBot 高 2.4%。PROC 用于评估隐藏意图完成、针对性澄清、跨会话偏好和规范复用、跨任务依赖推断以及欠规格请求推进等主动性能力。 -## 🤝 Agent-friendly Integration +## 🧩 扩展与工作流 -ReMe 既可以作为本地记忆服务，通过 CLI、HTTP API 或 MCP server 接入，也可以通过 Python API 嵌入宿主进程。不同 Agent 可以选择适合自身 -runtime 的路径。 +插件是可选的独立 Python distribution，可以贡献 Component、Step、Job backend 和配置，并通过配置显式启用。每日论文与 Auto Fin +均已独立打包，源码 distribution 位于 [`plugins/`](plugins/README.md)。 -| Agent | 推荐接入方式 | 接入后能力 | -|-----------------------------------------------|-------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------| -| **QwenPaw** | 通过 Python API 在进程内嵌入 ReMe。 | 复用宿主应用的生命周期和模型配置，同时保持 memory 本地、文件化。 | -| **Claude Code** | 启动 streamable HTTP MCP service，并安装 [integrations/claude_code/reme](integrations/claude_code/reme)。 | MCP recall tools、`reme-memory` skill，以及自动记录会话的 Stop hook。 | -| **Hermes** | 启动 HTTP service，并安装 [integrations/hermes_agent](integrations/hermes_agent)。 | 在模型调用前自动召回相关记忆，并在每轮对话完成后异步调用 `auto_memory`。 | -| **Other CLI-capable agents (OpenClaw/Codex)** | 复制或安装 [skills/reme_memory/SKILL.md](skills/reme_memory/SKILL.md)。 | 通过 CLI 搜索、读取和写入记忆；自动记录需要宿主 Agent 显式接入会话生命周期。 | +| 插件 | 能力 | +| ---------------------------------------------------------- | ------------------------------------------------------------------------------ | +| [每日论文](https://reme.agentscope.io/?doc=daily-paper-zh) | 发现并排序论文，使用 Agent 解读 PDF，生成文件化论文笔记和五分钟简报。 | +| [Auto Fin](https://reme.agentscope.io/?doc=auto-fin-zh) | 拉取主题相关财联社新闻，搜索 ReMe 历史材料并生成带 wikilink 的 Markdown 报告。 | -

集成演示

+安装、查看、校验、启用和卸载 ReMe 插件的方法见[插件管理](docs/zh/plugin_management.md)。 - - - - - - - - - - - - - - - - -
Auto MemoryAuto Dream
QwenPaw - QwenPaw Auto Memory 演示 - - QwenPaw Auto Dream 演示 -
Claude Code - Claude Code Auto Memory 演示 - - Claude Code Auto Dream 演示 -
+## 📚 文档 -## 🛠️ ReMe Operations +下列文档覆盖主要使用流程，并以当前代码的运行时契约为准。 + +| 文档 | 主要内容 | +| ------------------------------------------------------------------------ | ---------------------------------------------------------------------- | +| [快速开始](docs/zh/quick_start.md) | 安装 ReMe、启动服务，并执行首次文件和记忆操作。 | +| [Memory as File](docs/zh/memory_as_file.md) | 理解 workspace 分层、frontmatter、wikilink、chunk 和文件事实来源模型。 | +| [Auto Memory](docs/zh/auto_memory.md) | 保留过滤后的对话来源记录，并提炼可复用的 daily 记忆卡片。 | +| [Auto Resource](docs/zh/auto_resource.md) | 导入支持的文本资料，转换为可追溯来源的 daily 卡片。 | +| [Auto Dream](docs/zh/auto_dream.md) 与 [Auto Link](docs/zh/auto_link.md) | 将 daily 记忆整理为持续演化的 digest 节点和可读 wikilink 关系。 | +| [记忆检索](docs/zh/memory_search.md) | 使用 BM25、可选向量、RRF 融合、行号范围召回和渐进式链接扩展。 | +| [Proactive](docs/zh/proactive.md) | 安全读取兴趣主题，并将其接入宿主 Agent 的决策流程。 | +| [Agent 接入场景](docs/zh/reme_scene.md) | 在 CLI/SKILL.md、HTTP、MCP 和嵌入式 Python 集成之间选择。 | +| [框架说明](docs/zh/framework.md) | 理解 Application、Job、Step、Component、service、配置和生命周期边界。 | +| [ReMe 博客](https://agentscope-ai.github.io/ReMe/?doc=zh-reme-blog) | 了解完整产品故事、设计动机、使用示例和评测摘要。 | + +## 🛠️ 常用命令 运行 `reme help` 可查看完整 job 列表。常用 workspace 与维护命令如下： | 命令 | 作用 | -|-------------------------------------------|---------------------------------------------------------------| +| ----------------------------------------- | ------------------------------------------------------------- | | `reme status` | 查看有状态数据组件的内存估算及进程 RSS。 | | [`reme search`](docs/zh/memory_search.md) | 默认使用 BM25 和 wikilink 检索，启用后增加向量检索。 | | `reme read` / `reme write` / `reme edit` | 检查和维护 Markdown 记忆文件。 | @@ -363,7 +350,7 @@ runtime 的路径。 | `reme chat` | 与可感知 workspace 的只读 Agent 进行流式对话；需要 LLM 凭证。 | | `reme reindex` | 基于已有文件重建检索和 wikilink 索引。 | -## 🤝 社区与支持 +## 🤝 社区与贡献 - **问题反馈、需求与帮助**：请先查看 [Open Issues](https://github.com/agentscope-ai/ReMe/issues)；如无相关讨论，可新建 Issue 说明背景、目标行为和影响范围。