From c7dbf31c3fbbfcef299237f5fe0138f3eaad35f5 Mon Sep 17 00:00:00 2001 From: jinliyl <6469360+jinliyl@users.noreply.github.com> Date: Tue, 11 Aug 2026 13:31:11 +0800 Subject: [PATCH] docs: expand ReMe guides and agent integrations (#445) --- README.md | 18 +- README_ZH.md | 17 +- docs/en/reme-blog.md | 325 ++++++++++++++++++++++++++++++++++ docs/zh/reme-blog.md | 113 ++++++++---- plugins/claude_code/README.md | 6 +- skills/reme_memory/SKILL.md | 180 +++++++++++++++---- 6 files changed, 571 insertions(+), 88 deletions(-) create mode 100644 docs/en/reme-blog.md diff --git a/README.md b/README.md index 532c6f59..aa54b69d 100644 --- a/README.md +++ b/README.md @@ -51,7 +51,7 @@ memory, then continuously indexes, links, and consolidates that memory for futur [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](plugins/reme). + sessions when integrating with coding agents such as [Claude Code](plugins/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, @@ -258,14 +258,16 @@ through search, wikilinks, or proactive topics. ## 🤝 Agent-friendly Integration -ReMe runs as a local memory service and offers multiple integration paths: CLI, HTTP API, MCP server, and SDK. Different -agents can choose the path that fits their runtime while sharing the same local memory workspace. +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. Agents can choose the path that fits their runtime and share a local memory workspace +when appropriate. -| Agents | Recommended path | What works out of the box | -|------------------------------------------------------|-----------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------| -| **QwenPaw** | Embed ReMe via the Python SDK. | Reuse the app's own lifecycle and model config while keeping memory local and file-based. | -| **Claude Code** | Start ReMe as an MCP service and install [plugins/reme](plugins/reme). | MCP recall tools, a `reme-memory` skill, and a Stop hook that records sessions automatically. | -| **Other CLI-capable agents (OpenClaw/Hermes/Codex)** | Copy or install [skills/reme_memory/SKILL.md](skills/reme_memory/SKILL.md). | Search/read/write memory and call `auto_memory`, `auto_dream`, and `proactive` via the CLI. | +| 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 [plugins/claude_code/reme](plugins/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 [plugins/hermes_agent](plugins/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. |

Integration demos

diff --git a/README_ZH.md b/README_ZH.md index 8dd1246c..212566cb 100644 --- a/README_ZH.md +++ b/README_ZH.md @@ -46,7 +46,7 @@ Agent 能够可靠召回。 - **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](plugins/reme) 等 coding agent 时，跨会话保留代码风格、项目背景、仓库决策和流程经验。 +- **Coding agents**：在接入 [Claude Code](plugins/claude_code/reme) 等 coding agent 时，跨会话保留代码风格、项目背景、仓库决策和流程经验。 - **LLM Wiki**：把对话、笔记和资料转化为可检索、可追溯、可链接的 Markdown 知识库，由用户和 Agent 共同维护。 - **Self-evolving agents**：帮助 Agent 从经验中学习，把成功路径、失败尝试、可复用流程和阶段性反思沉淀为记忆。 @@ -247,14 +247,15 @@ ReMe 遵循 capture → index → consolidate → recall 的循环。对话和 ## 🤝 Agent-friendly Integration -ReMe 作为本地记忆服务运行，并提供 CLI、HTTP API、MCP server 和 SDK 等多种接入方式。不同 Agent 可以选择适合自身 runtime -的路径，同时共享同一个本地 memory workspace。 +ReMe 既可以作为本地记忆服务，通过 CLI、HTTP API 或 MCP server 接入，也可以通过 Python API 嵌入宿主进程。不同 Agent +可以选择适合自身 runtime 的路径，并按需共享同一个本地 memory workspace。 -| Agent | 推荐接入方式 | 开箱可用能力 | -|------------------------------------------------------|-------------------------------------------------------------------------|----------------------------------------------------------------------------------| -| **QwenPaw** | 通过 Python SDK 嵌入 ReMe。 | 复用应用自身生命周期和模型配置，同时保持 memory 本地、文件化。 | -| **Claude Code** | 以 MCP service 启动 ReMe，并安装 [plugins/reme](plugins/reme)。 | MCP recall tools、`reme-memory` skill，以及自动记录会话的 Stop hook。 | -| **Other CLI-capable agents (OpenClaw/Hermes/Codex)** | 复制或安装 [skills/reme_memory/SKILL.md](skills/reme_memory/SKILL.md)。 | 通过 CLI 搜索/读取/写入记忆，并调用 `auto_memory`、`auto_dream` 和 `proactive`。 | +| Agent | 推荐接入方式 | 接入后能力 | +|----------------------------------------|-----------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------| +| **QwenPaw** | 通过 Python API 在进程内嵌入 ReMe。 | 复用宿主应用的生命周期和模型配置，同时保持 memory 本地、文件化。 | +| **Claude Code** | 启动 streamable HTTP MCP service，并安装 [plugins/claude_code/reme](plugins/claude_code/reme)。 | MCP recall tools、`reme-memory` skill，以及自动记录会话的 Stop hook。 | +| **Hermes** | 启动 HTTP service，并安装 [plugins/hermes_agent](plugins/hermes_agent)。 | 在模型调用前自动召回相关记忆，并在每轮对话完成后异步调用 `auto_memory`。 | +| **Other CLI-capable agents (OpenClaw/Codex)** | 复制或安装 [skills/reme_memory/SKILL.md](skills/reme_memory/SKILL.md)。 | 通过 CLI 搜索、读取和写入记忆；自动记录需要宿主 Agent 显式接入会话生命周期。 |

集成演示

diff --git a/docs/en/reme-blog.md b/docs/en/reme-blog.md new file mode 100644 index 00000000..516bd7d4 --- /dev/null +++ b/docs/en/reme-blog.md @@ -0,0 +1,325 @@ +# ReMe: A Personal Knowledge Base That Keeps Growing After Every Conversation + +Every day, we talk with AI. + +It helps us analyze projects, read papers, and troubleshoot problems. We also tell it about our preferences, plans, and ideas we have not fully worked out yet. + +But most of the time, when a conversation ends, its value is locked away in the chat history. The next time we open a new window, the AI may remember a conclusion but not where it came from. It may find an old conversation but fail to connect it with materials we read or decisions we made later. + +Useful long-term memory should do more than preserve what once happened. It should keep organizing information, building connections, and bringing past knowledge back into future reasoning when needed. + +That is exactly what ReMe sets out to do. + +> **ReMe is a local-first, self-evolving personal knowledge base for AI agents. It continuously turns conversations and resources into readable, editable, searchable, and interconnected Markdown memories, while surfacing threads worth following.** + +GitHub: [https://github.com/agentscope-ai/ReMe](https://github.com/agentscope-ai/ReMe) + +Documentation: [https://docs.agentscope.io/reme](https://docs.agentscope.io/reme) + +

+ ReMe self-evolving personal knowledge base and public benchmark results +

+ +## A Memory Loop That Keeps Growing + +

+ ReMe self-evolving memory loop +

+ +ReMe is not another chatbot, nor does it try to replace the agents you already use. It is a local memory layer that agents such as QwenPaw, OpenClaw, Hermes, and Claude Code can share. + +Built around a set of ordinary files, it does four things: + +- Auto Memory extracts information worth keeping from conversations; +- Auto Resource turns external materials into traceable memories; +- Auto Dream consolidates daily memories into long-term knowledge; +- Index, Search, and Proactive bring old memories back into new tasks. + +Together, they form a `capture → index → consolidate → recall` loop: + +- Conversations and external resources are preserved first; +- Valuable information is organized into daily memories; +- Scattered events are consolidated into long-term knowledge nodes; +- Search, knowledge links, and interest discovery bring old memories back into future reasoning. + +Most importantly, this loop is centered not on an opaque database, but on files owned by the user. Indexes, graphs, and caches are merely derived state that can always be rebuilt. + +## Memory as File: Your Memories Are Your Files + +

+ ReMe Memory as File +

+ +ReMe's core design is called **Memory as File, File as Memory.** + +“Memory as File” means long-term memories are not hidden inside a product. They live in Markdown, JSONL, YAML, and original resource files within your workspace. You can open them directly in VS Code, Typora, or Obsidian, and back them up or move them with Git, cloud storage, or your own synchronization setup. + +“File as Memory” means each file is more than plain text. With YAML frontmatter, section structure, line ranges, and Wikilinks, it becomes a memory node that can be indexed, connected, and continuously evolved. + +For example, a long-term memory about writing preferences might look like this: + +```markdown +--- +name: "User preference: technical writing style" +description: Prefers stating the problem and outcome first, followed by technical details and examples. +kind: preference +--- + +The user wants technical articles to have a clear narrative and avoid unnecessary jargon. + +When writing an article, refer to [[digest/procedure/Technical content writing process.md]]. + +## Sources + +- [[daily/2026-08-07/content-discussion.md]] +``` + +Months later, even if you have forgotten the conversation, the agent can still read the preference, find the related process, and follow `Sources` back to the original context. + +This is also the key difference between ReMe and “black-box memory”: agents can organize memories, but users always retain the right to inspect, correct, move, and delete them. + +## Auto Memory: Turning Conversations into a Daily Journal + +

+ ReMe Auto Memory turns conversations into daily memories +

+ +A great deal of valuable information does not begin with “please remember this.” + +For example, you might say in a conversation: + +> “Let's not refactor the login module this week. We can do it after the customer demo. Upgrading dependencies directly caused compatibility issues last time, so let's add regression tests first.” + +This short passage contains project status, a time constraint, a lesson from a previous failure, and a next action. Auto Memory extracts these details from the conversation stream and writes them into a daily memory card, while preserving the original conversation in `session/dialog/`. + +```text +session/dialog/project-a.jsonl Original conversation, preserving what happened +daily/2026-08-07/project-a.md Memory card, optimized for reading +daily/2026-08-07.md Daily index, providing an overview +``` + +The next time the login module comes up, the agent does not need to search through the entire chat history. It can immediately see why the refactor was postponed, what went wrong before, and what should happen next. + +It is like having a recorder who is always present—not one that mechanically transcribes every word, but one that organizes what will still matter later. + +## Auto Resource: Bringing External Materials into the Same Memory System + +

+ ReMe Auto Resource turns external materials into traceable personal memories +

+ +Not all valuable information comes from conversations. Research materials, project documents, meeting notes, archived web pages, and structured data may all become part of a personal knowledge base. + +Auto Resource provides a general entry point for external materials. After a resource enters `resource/`, ReMe preserves the original and organizes its topics, key facts, and actionable information into daily cards with `source_resource` links. It currently supports text-based resources including Markdown, plain text, JSON, JSONL, CSV, YAML, and HTML. + +In other words, Auto Memory builds personal knowledge from conversations, while Auto Resource builds it from non-conversational materials. Both streams flow into the same daily memory layer, where ReMe indexes, consolidates, and retrieves them together. + +### Daily Paper: An Example External-Resource Workflow + +Daily Paper is an optional cookbook built on this file-based memory system. It collects papers from the weekly and monthly Hugging Face Papers rankings, removes items recommended recently, ranks the remaining papers, selects three, saves their PDFs, and generates Chinese paper notes and a briefing that takes about five minutes to read. + +Imagine that you regularly follow research on agent memory. Each morning, instead of receiving only three links, you get three detailed notes already saved locally. The briefing points to the original notes through Wikilinks, and each note links back to its PDF. A month later, when you ask, “What recent methods compress long-term memory?”, those materials are already in the same retrieval system. There is no need to search through browser history again. + +Daily Paper demonstrates how Auto Resource can be composed into a concrete workflow, but the external-resource pipeline is not limited to papers. + +## Auto Dream: Growing Daily Notes into Connected Long-Term Knowledge + +

+ ReMe Auto Dream extracts, classifies, and consolidates long-term knowledge from daily memories while adding Wikilinks +

+ +As daily notes accumulate, a new problem emerges: the information is all there, but it remains scattered across different dates. + +Suppose conversations and external materials give you three pieces of information about the same problem: + +- The first time a build hung, clearing the cache did not help; +- A project document later confirmed that insufficient Node.js memory was the root cause; +- A third note added that the issue occurs more often in large TypeScript projects. + +Auto Dream scans all changed daily files, merges evidence that points to the same abstraction, keeps only reusable memory units, and writes them into three categories of long-term memory: + +- `Personal`: preferences, conventions, and constraints specific to a user, team, or project; +- `Procedure`: repeatable processes, methods, and troubleshooting guides; +- `Wiki`: general definitions, principles, observations, and knowledge. + +For example, the information above would become `digest/procedure/Troubleshooting frozen frontend builds.md`, which records the triggering conditions, diagnostic sequence, failed attempts, solution, and scope of applicability—instead of simply concatenating several daily notes. + +When consolidating each memory unit, Auto Dream first searches existing nodes across `personal`, `procedure`, and `wiki`, distinguishing between the “same abstraction” and “related knowledge.” The same abstraction determines how the target node evolves: + +- `CREATE`: no equivalent memory exists, so create a new node; +- `CORROBORATE`: the same conclusion appears again, so add its source and strengthen confidence; +- `REFINE`: new material adds conditions, steps, or details; +- `CORRECT`: new information corrects an earlier conclusion. + +Related knowledge is written into the body as Wikilinks during the same consolidation process. This is Auto Link. For example, “Troubleshooting frozen frontend builds” can connect general knowledge, team preferences, and original evidence at once: + +```markdown +This issue often occurs in [[digest/wiki/Large TypeScript projects.md]]. When resolving it, +follow the “add regression tests first” convention in [[digest/personal/Team change preferences.md]]. + +## Sources + +- [[daily/2026-08-07/build-debug.md|Build troubleshooting record]] provides the root cause and applicable scenarios. +``` + +Knowledge evolves and links are created in the same workflow. Relationships are not invisible edges hidden in a graph database; they are readable, editable content in the files themselves. The files can rebuild the graph—the graph never takes control of the files. + +## Memory Index: Turning Ordinary Files into a Searchable Memory Network + +

+ ReMe Memory Index build process +

+ +Markdown is easy for people to read, but if files are merely piled into directories, agents still struggle to find them quickly. ReMe continuously watches `daily/`, `digest/`, and `resource/`, synchronizing additions, changes, and deletions to a rebuildable index. + +A Markdown file is parsed into: + +- One file node containing file-level information such as its path and frontmatter; +- Multiple semantic chunks split, wherever possible, along the boundaries of headings, paragraphs, lists, and code blocks, while retaining section structure and line numbers; +- Multiple Wikilink edges recording what the file points to and what points back to it. + +For retrieval, ReMe can combine three types of signals: + +| Retrieval signal | Problem it solves | Example | +|------------------|-------------------|---------| +| BM25 keywords | Exact names, terms, and identifiers must not be missed | “CATL”, “issue #184” | +| Embedding vectors | Semantically similar wording should still match | “build frozen” and “packaging stage not responding” | +| Wikilink graph | Reveal upstream and downstream relationships after finding a node | From “cobalt” to “ternary cathodes” and related research notes | + +The default configuration enables BM25 and Wikilink expansion out of the box. Embeddings are optional and participate in vector retrieval only when enabled. Indexes, graphs, and caches are stored in `metadata/`; even if deleted, they can be rebuilt from the user's source files. + +## Memory Search: Find the Answer First, Then Expand Relationships Progressively + +

+ ReMe hybrid search and progressive expansion +

+ +Many RAG systems put all Top-K passages into the context at once. This is simple, but it creates two problems: isolated chunks lack context, while expanding every neighbor's full text quickly consumes tokens. + +ReMe's hybrid search lets BM25 and optional vector retrieval produce their own candidates, then fuses the rankings with RRF. Instead of directly comparing BM25 scores with cosine similarities—two different scales—RRF combines where each result appears in the two ranked lists. + +After retrieval, information expands progressively in three layers: + +1. **Start with the matching passage**: return the most relevant chunk, file path, and line numbers; +2. **Then inspect the relationship directory**: show the file's outgoing and incoming links, including only each neighbor's path, name, description, and anchor rather than loading all of its content immediately; +3. **Finally, go deeper as needed**: the agent decides which relationship is genuinely relevant, then reads the original file or continues traversing the graph. + +For example, you ask: “What was the name of the book about attention that Alice recommended last time?” + +The first step may find a dinner note that says only, “The title contains the word ‘deep.’” The result also shows that the note links to Alice's personal node and is backlinked by reading notes for *Deep Work*. + +The agent does not need to load Alice's entire profile, every reading note, and a whole month of journal entries into its context. It only needs to follow the most relevant link and read once more before answering: + +> It was *Deep Work*. Alice recommended it at that dinner, and you later read Chapter 3 and left notes. + +This resembles human association: first recall a fragment, then follow the trail to recover the full context. + +## Proactive: Discovering Needs You Have Not Yet Put into Words + +

+ ReMe Proactive's two-way memory loop +

+ +At this point, ReMe has two input streams that continuously enrich the knowledge base: + +- Auto Memory distills personal context from ongoing conversations; +- Auto Resource adds new knowledge from external materials. + +Proactive reverses the direction. From accumulated conversations and materials, it discovers topics you have not yet resolved or may want to pursue, along with information you have not noticed but that closely relates to your recent work. These discoveries can then guide what external knowledge enters the system next. + +For example, over the past week you separately mentioned that: + +- Search results lack sources; +- Long documents lose section context after chunking; +- You want to compare several agent-memory evaluation methods. + +Even though you never explicitly said, “Help me systematically study the explainability of memory retrieval,” Auto Dream can distill an interest topic from these daily memories: + +```yaml +title: Evaluating the explainability of memory retrieval +reason: The user has recently focused on source tracing, structure-aware chunking, and memory evaluation. +evidence: daily/2026-08-07/search-discussion.md +keywords: + - memory search + - source attribution + - benchmark +``` + +In a future beta release, after reading this topic through Proactive, a host agent could ask at an appropriate moment, “Would you like me to turn the retrieval issues we discussed recently into an evaluation plan?” It could also use the topic to initiate a user-authorized research workflow. Users would not need to identify and explicitly specify their interests and scope in advance; external resources related to needs implicit in their conversations could continue flowing into the knowledge base. + +There is an important boundary: **ReMe's Proactive feature only reads and exposes interest topics. It does not independently access the internet, send notifications, or rewrite the knowledge base.** +It does not guess your interests from nowhere. It surfaces clues that already appeared in your behavior and conversations but have not yet been explicitly stated. + +## Performance: Can It Retrieve Information from Very Long Histories? + +ReMe uses LongMemEval and BEAM to evaluate memory across multiple sessions and extremely long conversations. During evaluation, the agent can use ReAct to search and read over multiple rounds, generate an answer, and then receive an LLM-as-judge score. + +| Benchmark | Setting | Sample size | Agentic score | Primary capabilities tested | +|-----------|---------|------------:|---------------:|-----------------------------| +| **LongMemEval cleaned-s** | **Overall** | **500 questions** | **89.4%** | Cross-session retrieval, knowledge updates, and temporal reasoning | +| BEAM | 100K context | 20 cases / 400 questions | 66.1% | Ten types of long-context memory tasks | +| BEAM | 1M context | 35 cases / 700 questions | 65.0% | Larger-scale, ultra-long conversation settings | + +LongMemEval cleaned-s includes single-session facts, preferences, multi-session reasoning, knowledge updates, temporal reasoning, and other question types. ReMe achieved an overall Agentic score of 89.4% across 500 questions. See the [LongMemEval evaluation guide](../../benchmark/longmemeval/README.md) for the complete workflow and breakdown. + +BEAM covers ten categories of tasks, including contradiction resolution, event ordering, information extraction, knowledge updates, multi-session reasoning, preference following, summarization, and temporal reasoning. ReMe scored 66.1% on 20 cases / 400 questions with a 100K context and 65.0% on 35 cases / 700 questions with a 1M context. See the [BEAM evaluation guide](../../benchmark/beam/README.md) for the complete setup. + +ReMe also uses $\pi$-Bench to evaluate the potential of multi-session reasoning to improve agent proactivity. The PROC score in $\pi$-Bench evaluates capabilities including directly fulfilling hidden intent, guiding targeted clarification, recovering cross-session preferences, reusing cross-session conventions, inferring cross-task dependencies, and advancing underspecified requests. Across five user personas, ReMe Agent achieved an average PROC score of 0.580, outperforming NanoBot by 2.4% under the same test-model configuration. See the [$\pi$-Bench paper](https://arxiv.org/abs/2605.14678) for details about the benchmark. + +## Who Is ReMe For? + +### People Who Use Agents Directly + +If you want AI to understand you continuously throughout a long-term collaboration, ReMe lets your personal assistant stop starting from scratch. Your preferences, project context, important materials, and past decisions accumulate through ongoing conversations and can be found again when they are genuinely relevant. + +Researchers, engineers, analysts, and other knowledge workers all fall into this category. Researchers can connect papers, discussions, and reading notes; engineers can preserve project decisions and cross-session troubleshooting experience; analysts can build an evolving record of events, perspectives, and sources. Their professions differ, but they share the same need: AI that can understand the past, accumulate experience, and recover supporting context for the next task. + +### Developers Who Build Agents + +If you are building an agent, harness, or AI product, ReMe provides an independent long-term memory layer. Through its CLI, HTTP API, MCP Server, or Python API, you can let multiple agents share the same file-based workspace without reimplementing memory extraction, knowledge organization, hybrid retrieval, and relationship expansion for every application. + +Files remain the source of truth, while indexes and caches can be rebuilt at any time. This also makes it easier to determine whether an incorrect retrieval originated in the source material, memory consolidation, or the retrieval pipeline. + +Ultimately, ReMe is for users and developers who want AI to do more than “answer this one request”: they want it to understand the past, accumulate experience, and know them better over the course of a long-term collaboration. We want agents to understand you better the more you use them—but that understanding should not live in a black box that you cannot inspect, correct, or take with you. + +ReMe's answer is straightforward: + +- Memories are files owned by the user; +- Original information preserves what happened, while long-term knowledge preserves the abstraction; +- New conversations and resources keep flowing in, while existing knowledge is continuously supplemented and corrected; +- Every conclusion can be traced to relationships and sources through Wikilinks; +- Indexes and caches serve the files rather than replace them; +- Agents can remember, organize, search, and discover, but users always retain ultimate control. + +When these mechanisms come together, a personal knowledge base is no longer a repository you must maintain by hand. + +It remembers a little more after every conversation and understands a little more after every new resource. At night, it reorganizes scattered experiences. When a future question arises, it follows the connections between pieces of knowledge and brings back the memory you actually need. + +That is what ReMe sets out to do: **make memory not only persistent, but continuously evolving.** + +## Integrate ReMe with the Agents You Already Use + +ReMe can run as a local memory service accessed through its CLI, HTTP API, or MCP Server, or it can be embedded in a host process through its Python API. Different agents can choose the integration that best fits their runtime environment and share the same local memory workspace when needed. + +| Agent | Recommended integration | Capabilities after integration | +|-------|-------------------------|--------------------------------| +| **QwenPaw** | Embed ReMe in-process through the Python API. | Reuse the host application's lifecycle and model configuration while keeping memories local and file-based. | +| **Claude Code** | Start the streamable HTTP MCP Service and install [`plugins/claude_code/reme`](../../plugins/claude_code/reme). | MCP memory-recall tools, the `reme-memory` skill, and a Stop hook that automatically records sessions. | +| **Hermes** | Start the HTTP Service and install [`plugins/hermes_agent`](../../plugins/hermes_agent). | Automatically recall relevant memories before model calls and invoke `auto_memory` asynchronously after each conversation turn. | +| **OpenClaw, Codex, and other CLI-capable agents** | Copy or install [`skills/reme_memory/SKILL.md`](../../skills/reme_memory/SKILL.md). | Search, read, and write memories through the CLI; automatic recording requires the host agent to integrate explicitly with the conversation lifecycle. | + +For installation, configuration, and integration demos, see the [README](../../README.md). + +## Contributions Welcome + +ReMe is open source, and we welcome the community's help in making this self-evolving memory system more complete: + +- Integrate more agents and harnesses so different runtime environments can use the same user-owned long-term memory; +- Contribute new Auto Resource sources and workflows so papers, news, and other public materials can continuously enter the knowledge base; +- Improve Auto Memory, Auto Dream, Auto Link, hybrid search, and Proactive so memories are organized more accurately, relationships are clearer, and retrieval is more reliable; +- Add application examples, evaluation tasks, and diagnostic reports to help us understand successes and failures in real long-term use; +- Improve documentation and tests, or share your needs and ideas for personal AI memory through an Issue. + +Whether it is a code contribution, a use case, a bug report, or a new memory workflow, every contribution can bring ReMe closer to a truly readable, controllable, and continuously evolving personal knowledge base. + +Contribution guide: [https://docs.agentscope.io/reme/latest/en/contribution](https://docs.agentscope.io/reme/latest/en/contribution) diff --git a/docs/zh/reme-blog.md b/docs/zh/reme-blog.md index 76182f46..c086cda3 100644 --- a/docs/zh/reme-blog.md +++ b/docs/zh/reme-blog.md @@ -10,7 +10,8 @@ 这正是 ReMe 想解决的事情。 -> **ReMe 是一个面向 AI Agent 的、local-first 的自进化个人知识库。它让对话与资料持续沉淀为可读、可编辑、可检索、相互链接的 Markdown 记忆，并从中提炼值得继续关注的线索。** +> **ReMe 是一个面向 AI Agent 的、local-first 的自进化个人知识库。它让对话与资料持续沉淀为可读、可编辑、可检索、相互链接的 +Markdown 记忆，并从中提炼值得继续关注的线索。** 项目地址：[https://github.com/agentscope-ai/ReMe](https://github.com/agentscope-ai/ReMe) @@ -26,7 +27,8 @@ ReMe 自进化记忆循环

-ReMe 不是另一个聊天机器人，也不试图替代你正在使用的 Agent。它更像一个可以被 QwenPaw、OpenClaw、Hermes、Claude Code 等 Agent 共享的本地记忆层。 +ReMe 不是另一个聊天机器人，也不试图替代你正在使用的 Agent。它更像一个可以被 QwenPaw、OpenClaw、Hermes、Claude Code 等 Agent +共享的本地记忆层。 它围绕一套普通文件，完成四件事： @@ -50,11 +52,13 @@ ReMe 不是另一个聊天机器人，也不试图替代你正在使用的 Agent ReMe Memory as File

-ReMe 的核心设计叫作：**Memory as File, File as Memory。** +ReMe 的核心设计称为 **Memory as File, File as Memory。** -“Memory as File”意味着，长期记忆不是藏在产品内部，而是落在 workspace 里的 Markdown、JSONL、YAML 和原始资源文件中。你可以用 VS Code、Typora 或 Obsidian 直接打开，也可以用 Git、网盘或自己的同步方案备份和迁移。 +“Memory as File”意味着，长期记忆不是藏在产品内部，而是落在 workspace 里的 Markdown、JSONL、YAML 和原始资源文件中。你可以用 VS +Code、Typora 或 Obsidian 直接打开，也可以用 Git、网盘或自己的同步方案备份和迁移。 -“File as Memory”意味着，每个文件又不只是普通文本。它可以带有 YAML frontmatter、章节结构、行号范围和 Wikilink，成为一个可索引、可连接、可继续演化的记忆节点。 +“File as Memory”意味着，每个文件又不只是普通文本。它可以带有 YAML frontmatter、章节结构、行号范围和 +Wikilink，成为一个可索引、可连接、可继续演化的记忆节点。 例如，一条关于写作偏好的长期记忆可以是： @@ -90,10 +94,11 @@ kind: preference > “这周先不要重构登录模块，客户演示之后再做。上次直接升级依赖导致兼容问题，这次先补回归测试。” -这段话里同时包含了项目状态、时间约束、一次失败经验和后续行动。Auto Memory 会把它从聊天流水中提炼出来，写成当天的一张 daily 记忆卡片；原始对话则继续保存在 `session/dialog/` 中。 +这段话里同时包含了项目状态、时间约束、一次失败经验和后续行动。Auto Memory 会把它从聊天流水中提炼出来，写成当天的一张 daily +记忆卡片；原始对话则继续保存在 `session/dialog/` 中。 ```text -session/dialog/project-a.jsonl 原始对话，负责可信 +session/dialog/project-a.jsonl 原始对话，负责保留现场 daily/2026-08-07/project-a.md 记忆卡片，负责好读 daily/2026-08-07.md 当天索引，负责总览 ``` @@ -110,15 +115,19 @@ daily/2026-08-07.md 当天索引，负责总览 并不是所有有价值的信息都来自对话。研究资料、项目文档、会议纪要、网页存档和结构化数据，同样可能成为个人知识库的一部分。 -Auto Resource 提供了一条更通用的外部资料入口。资料进入 `resource/` 后，ReMe 保留原文，再把主题、关键事实和可行动信息整理为带有 `source_resource` 链接的 daily 卡片。当前可以处理 Markdown、纯文本、JSON、JSONL、CSV、YAML 和 HTML 等文本类资料。 +Auto Resource 提供了一条更通用的外部资料入口。资料进入 `resource/` 后，ReMe 保留原文，再把主题、关键事实和可行动信息整理为带有 +`source_resource` 链接的 daily 卡片。当前可以处理 Markdown、纯文本、JSON、JSONL、CSV、YAML 和 HTML 等文本类资料。 -这意味着，Auto Memory 负责从对话建立个人知识，Auto Resource 负责从非对话资料建立个人知识。两条输入最终进入同一个 daily 记忆层，再由 ReMe 统一索引、整合和检索。 +这意味着，Auto Memory 负责从对话建立个人知识，Auto Resource 负责从非对话资料建立个人知识。两条输入最终进入同一个 daily +记忆层，再由 ReMe 统一索引、整合和检索。 ### Daily Paper：外部资料工作流的一个例子 -Daily Paper 是建立在这套文件化记忆之上的可选 Cookbook。它会从 Hugging Face Papers 的周榜和月榜收集论文，去除近期已经推荐过的内容，排序后精选三篇，保存 PDF，并生成中文论文笔记与一份约五分钟可读完的简报。 +Daily Paper 是建立在这套文件化记忆之上的可选 Cookbook。它会从 Hugging Face Papers 的周榜和月榜收集论文，去除近期已经推荐过的内容，排序后精选三篇，保存 +PDF，并生成中文论文笔记与一份约五分钟可读完的简报。 -想象一下，你持续关注 Agent Memory：每天早上收到的不只是三个论文链接，而是三篇已经保存到本地的详细笔记。简报通过 Wikilink 指向原始笔记，原始笔记又能回到 PDF。一个月后再问“最近有哪些方法在做长期记忆压缩”，这些材料已经进入同一套检索系统，不需要重新从浏览器历史里寻找。 +想象一下，你持续关注 Agent Memory：每天早上收到的不只是三个论文链接，而是三篇已经保存到本地的详细笔记。简报通过 Wikilink +指向原始笔记，原始笔记又能回到 PDF。一个月后再问“最近有哪些方法在做长期记忆压缩”，这些材料已经进入同一套检索系统，不需要重新从浏览器历史里寻找。 Daily Paper 展示了 Auto Resource 可以怎样被组合成具体工作流，但外部资料入口并不局限于论文。 @@ -136,7 +145,7 @@ Daily Paper 展示了 Auto Resource 可以怎样被组合成具体工作流， - 第二次在项目文档中确认根因是 Node 内存不足； - 第三次又补充了大型 TypeScript 项目下更容易触发这个问题。 -Auto Dream 会一起扫描发生变化的 daily 文件，合并表达同一抽象的证据，只保留值得复用的记忆单元，再按内容写入三类长期记忆： +Auto Dream 会扫描所有发生变化的 daily 文件，合并指向同一抽象的证据，只保留值得复用的记忆单元，再按内容写入三类长期记忆： - `Personal`：用户、团队或项目特定的偏好、约定和约束； - `Procedure`：可以再次执行的流程、方法和排查手册； @@ -170,7 +179,8 @@ Auto Dream 会一起扫描发生变化的 daily 文件，合并表达同一抽 ReMe Memory Index 构建过程

-Markdown 适合人读，但如果只是把文件堆进目录，Agent 仍然很难快速找到它们。ReMe 会持续监听 `daily/`、`digest/` 和 `resource/`，将新增、修改和删除同步到可重建的索引中。 +Markdown 适合人读，但如果只是把文件堆进目录，Agent 仍然很难快速找到它们。ReMe 会持续监听 `daily/`、`digest/` 和 `resource/`， +将新增、修改和删除同步到可重建的索引中。 一份 Markdown 会被解析为： @@ -180,13 +190,14 @@ Markdown 适合人读，但如果只是把文件堆进目录，Agent 仍然很 在检索侧，ReMe 可以组合三类信号： -| 检索信号 | 解决的问题 | 例子 | -|---|---|---| -| BM25 关键词 | 精确名称、术语和编号不能丢 | “宁德时代”“issue #184” | -| Embedding 向量 | 用户换了一种说法，也要理解语义接近 | “构建卡死”与“打包阶段没有响应” | -| Wikilink 图谱 | 命中一个节点后，看到它的上下游关系 | 从“钴”找到“三元正极”和相关调研记录 | +| 检索信号 | 解决的问题 | 例子 | +|----------------|------------------------------------|------------------------------------| +| BM25 关键词 | 精确名称、术语和编号不能丢 | “宁德时代”“issue #184” | +| Embedding 向量 | 用户换了一种说法，也要理解语义接近 | “构建卡死”与“打包阶段没有响应” | +| Wikilink 图谱 | 命中一个节点后，看到它的上下游关系 | 从“钴”找到“三元正极”和相关调研记录 | -默认配置开箱启用 BM25 与 Wikilink 展开，Embedding 是可选能力，开启后才会参与向量召回。索引、图谱和缓存都写在 `metadata/`，即使删除也可以根据用户的源文件重新构建。 +默认配置开箱启用 BM25 与 Wikilink 展开，Embedding 是可选能力，开启后才会参与向量召回。索引、图谱和缓存都写在 `metadata/`， +即使删除也可以根据用户的源文件重新构建。 ## Memory Search：先找到答案，再沿着关系渐进展开 @@ -194,9 +205,11 @@ Markdown 适合人读，但如果只是把文件堆进目录，Agent 仍然很 ReMe 混合搜索与渐进式展开

-很多 RAG 系统会一次性把 Top-K 文本全部塞进上下文。这样做简单，却容易带来两个问题：孤立切片缺少上下文，而把邻居正文全部展开又会迅速消耗 token。 +很多 RAG 系统会一次性把 Top-K 文本全部塞进上下文。这样做简单，却容易带来两个问题：孤立切片缺少上下文，而把邻居正文全部展开又会迅速消耗 +token。 -ReMe 的混合搜索先让 BM25 与可选的向量检索各自召回候选，再使用 RRF 按排名融合。RRF 不强行比较 BM25 分数与余弦相似度这两种不同量纲，而是综合一个结果在两张榜单中的位置。 +ReMe 的混合搜索先让 BM25 与可选的向量检索各自召回候选，再使用 RRF 按排名融合。RRF 不强行比较 BM25 +分数与余弦相似度这两种不同量纲，而是综合一个结果在两张榜单中的位置。 召回之后，信息按三层渐进式展开： @@ -225,7 +238,7 @@ Agent 不需要把 Alice 的全部档案、所有读书笔记和整个月的日 - Auto Memory 从持续发生的对话中沉淀个人上下文； - Auto Resource 从外部资料中补充新的知识。 -Proactive 则把方向反过来：它从已经积累的对话和资料中，发现你仍未解决或可能希望继续推进的主题，以及你尚未关注，但却与你近期工作紧密相关的信息。从而反哺输入流，为外部知识的补充指明新的路径。 +Proactive 则把方向反过来：它从已经积累的对话和资料中，发现你仍未解决或可能希望继续推进的主题，以及你尚未关注、但与近期工作紧密相关的信息。这些发现会反哺输入流，为补充外部知识指明新的路径。 例如，你最近一周分别聊过： @@ -245,26 +258,34 @@ keywords: - benchmark ``` -在未来的beta版本中，上层 Agent将会 通过 Proactive 读取这个主题后，可以选择在合适的时机追问：“要不要把最近讨论过的检索问题整理成一份评测方案？”也可以据此启动一个经过用户授权的资料收集流程。不需要用户思考并显示指定自己的兴趣关键词与范围，与会话中潜在体现需求相关的外部资料也会源源不断进入知识库。 +在未来的 beta 版本中，上层 Agent 通过 Proactive +读取这个主题后，可以选择在合适的时机追问：“要不要把最近讨论过的检索问题整理成一份评测方案？”也可以据此启动一个经过用户授权的资料收集流程。用户不需要预先梳理并显式指定自己的兴趣关键词和范围；与对话中潜在需求相关的外部资料，也可以持续进入知识库。 -这里有一个重要边界：**ReMe 的 Proactive 本身只读取并暴露兴趣主题，不会擅自联网、推送或改写知识库。** 它不是凭空猜测你的兴趣，而是让那些已经出现在行为和对话中、却还没有被明确表达的线索浮出水面。 +这里有一个重要边界：**ReMe 的 Proactive 本身只读取并暴露兴趣主题，不会擅自联网、推送或改写知识库。** +它不是凭空猜测你的兴趣，而是让那些已经出现在行为和对话中、却还没有被明确表达的线索浮出水面。 ## Performance：它真的能从很长的历史里找回信息吗？ +ReMe 使用 LongMemEval 和 BEAM 验证多会话与超长对话中的记忆能力。评测时，Agent 可以用 ReAct 方式进行多轮搜索和读取，生成答案后再由 +LLM-as-judge 评分。 -ReMe 使用 LongMemEval 和 BEAM 验证多会话与超长对话中的记忆能力。评测时，Agent 可以用 ReAct 方式进行多轮搜索和读取，生成答案后再由 LLM-as-judge 评分。 +| 基准 | 设置 | 样本量 | Agentic 得分 | 主要检验内容 | +|---------------------------|-------------|------------------:|-------------:|--------------------------------| +| **LongMemEval cleaned-s** | **整体** | **500 题** | **89.4%** | 跨会话检索、知识更新与时间推理 | +| BEAM | 100K 上下文 | 20 cases / 400 题 | 66.1% | 十类长上下文记忆任务 | +| BEAM | 1M 上下文 | 35 cases / 700 题 | 65.0% | 更大规模的超长对话设置 | -| 基准 | 设置 | 样本量 | Agentic 得分 | 主要检验内容 | -|---|---|---:|---:|---| -| **LongMemEval cleaned-s** | **整体** | **500 题** | **89.4%** | 跨会话检索、知识更新与时间推理 | -| BEAM | 100K 上下文 | 20 cases / 400 题 | 66.1% | 十类长上下文记忆任务 | -| BEAM | 1M 上下文 | 35 cases / 700 题 | 65.0% | 更大规模的超长对话设置 | +LongMemEval cleaned-s 包含单会话事实、偏好、多会话推理、知识更新和时间推理等题型。ReMe 在 500 道问题上取得 89.4% 的整体 +Agentic 得分。完整流程和分项结果见 [LongMemEval 评测说明](../../benchmark/longmemeval/README_ZH.md)。 -LongMemEval cleaned-s 包含单会话事实、偏好、多会话推理、知识更新和时间推理等题型。ReMe 在 500 道问题上取得 89.4% 的整体 Agentic 得分。完整流程和分项结果见 [LongMemEval 评测说明](../../benchmark/longmemeval/README_ZH.md)。 +BEAM 覆盖矛盾消解、事件排序、信息抽取、知识更新、多会话推理、偏好遵循、摘要和时间推理等十类任务。ReMe 在 100K 设置下的 20 +cases / 400 题上取得 66.1%，在 1M 设置下的 35 cases / 700 题上取得 +65.0%。完整设置见 [BEAM 评测说明](../../benchmark/beam/README_ZH.md)。 -BEAM 覆盖矛盾消解、事件排序、信息抽取、知识更新、多会话推理、偏好遵循、摘要和时间推理等十类任务。ReMe 在 100K 设置下的 20 cases / 400 题上取得 66.1%，在 1M 设置下的 35 cases / 700 题上取得 65.0%。完整设置见 [BEAM 评测说明](../../benchmark/beam/README_ZH.md)。 - -此外，ReMe 还使用 $\pi$-Bench 验证了基于多会话推理提升 Agent 主动性的潜力。$\pi$-Bench 中的 PROC 分数旨在评估 Agent 在隐藏意图直接完成、针对性澄清引导、跨会话偏好恢复、跨会话规范复用、跨任务依赖推断以及欠规格请求推进等方面的主动性能力。ReMe Agent 在 5 种用户角色（User Persona）上平均取得 0.580 的 PROC 分数，超出相同测试模型配置的 NanoBot 2.4%。完整设置见 [$\pi$-Bench 评测说明](../../benchmark/pibench/README.md)。 +此外，ReMe 还使用 $\pi$-Bench 验证了基于多会话推理提升 Agent 主动性的潜力。$\pi$-Bench 中的 PROC 分数旨在评估 Agent +在隐藏意图直接完成、针对性澄清引导、跨会话偏好恢复、跨会话规范复用、跨任务依赖推断以及欠规格请求推进等方面的主动性能力。ReMe +Agent 在 5 种用户角色（User Persona）上平均取得 0.580 的 PROC 分数，超出相同测试模型配置的 NanoBot +2.4%。关于该基准的详细介绍见 [$\pi$-Bench 论文](https://arxiv.org/abs/2605.14678)。 ## ReMe 能帮谁？ @@ -272,15 +293,18 @@ BEAM 覆盖矛盾消解、事件排序、信息抽取、知识更新、多会话 如果你希望 AI 在长期协作中持续了解你，ReMe 可以让个人助理不再每次都从零开始。你的偏好、项目背景、重要资料和过去做过的决定，会在持续对话中沉淀下来，并在真正相关的时候被重新找到。 -研究者、工程师、分析师和其他知识工作者都属于这一类直接用户。研究者可以让论文、讨论和阅读笔记彼此连接；工程师可以保留项目决定与跨会话排障经验；分析师可以持续积累事件、观点与来源。职业不同，共同需求都是让 AI 能够理解过去、积累经验，并在下一次任务中找回依据。 +研究者、工程师、分析师和其他知识工作者都属于这一类直接用户。研究者可以让论文、讨论和阅读笔记彼此连接；工程师可以保留项目决定与跨会话排障经验；分析师可以持续积累事件、观点与来源。职业不同，共同需求都是让 +AI 能够理解过去、积累经验，并在下一次任务中找回依据。 ### 构建 Agent 的开发者 -如果你正在构建 Agent、Harness 或 AI 产品，ReMe 提供了一层可以独立接入的长期记忆基础设施。你可以通过 CLI、HTTP API、MCP Server 或 SDK，让不同 Agent 共享同一个文件化 workspace，而不必为每个应用重新实现记忆抽取、知识整理、混合检索和关系展开。 +如果你正在构建 Agent、Harness 或 AI 产品，ReMe 提供了一层可以独立接入的长期记忆基础设施。你可以通过 CLI、HTTP API、MCP Server +或 Python API，让不同 Agent 共享同一个文件化 workspace，而不必为每个应用重新实现记忆抽取、知识整理、混合检索和关系展开。 文件是事实来源，索引与缓存可以随时重建，也更容易定位一次错误召回究竟来自原始资料、记忆整理还是检索链路。 -归根结底，ReMe 适合那些希望 AI 不只“回答这一次”，还能够理解过去、积累经验，并在长期协作中越来越贴近自己的用户和开发者。我们希望 Agent 越用越懂你，但“懂”不应该建立在一个无法查看、无法修正、无法带走的黑盒上。 +归根结底，ReMe 适合那些希望 AI 不只“回答这一次”，还能够理解过去、积累经验，并在长期协作中越来越懂自己的用户和开发者。我们希望 +Agent 越用越懂你，但“懂”不应该建立在一个无法查看、无法修正、无法带走的黑盒上。 ReMe 给出的答案很朴素： @@ -297,6 +321,20 @@ ReMe 给出的答案很朴素： 这就是 ReMe 想做的事：**让记忆不只被保存，也能持续进化。** +## 接入你正在使用的 Agent + +ReMe 既可以作为本地记忆服务，通过 CLI、HTTP API 或 MCP Server 接入，也可以通过 Python API 嵌入宿主进程。不同 Agent +可以选择适合自身运行环境的路径，并按需共享同一个本地 memory workspace。 + +| Agent | 推荐接入方式 | 接入后能力 | +|----------------------------------------|--------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------| +| **QwenPaw** | 通过 Python API 在进程内嵌入 ReMe。 | 复用宿主应用的生命周期和模型配置，同时保持记忆本地、文件化。 | +| **Claude Code** | 启动 streamable HTTP MCP Service，并安装 [`plugins/claude_code/reme`](../../plugins/claude_code/reme)。 | MCP 记忆召回工具、`reme-memory` skill，以及自动记录会话的 Stop hook。 | +| **Hermes** | 启动 HTTP Service，并安装 [`plugins/hermes_agent`](../../plugins/hermes_agent)。 | 在模型调用前自动召回相关记忆，并在每轮对话完成后异步调用 `auto_memory`。 | +| **OpenClaw、Codex 等支持 CLI 的 Agent** | 复制或安装 [`skills/reme_memory/SKILL.md`](../../skills/reme_memory/SKILL.md)。 | 通过 CLI 搜索、读取和写入记忆；自动记录需要宿主 Agent 显式接入会话生命周期。 | + +安装、配置与集成演示可查看 [README 中文版](../../README_ZH.md)。 + ## 欢迎贡献 ReMe 已经开源，我们也欢迎社区一起把这套自进化记忆系统做得更完整： @@ -309,5 +347,4 @@ ReMe 已经开源，我们也欢迎社区一起把这套自进化记忆系统做 无论是一段代码、一份使用案例、一次问题反馈，还是一个新的记忆工作流，都可能帮助 ReMe 更接近真正可读、可控、可持续进化的个人知识库。 - 贡献指南：[https://docs.agentscope.io/reme/latest/en/contribution](https://docs.agentscope.io/reme/latest/en/contribution) diff --git a/plugins/claude_code/README.md b/plugins/claude_code/README.md index a295b294..541c8aed 100644 --- a/plugins/claude_code/README.md +++ b/plugins/claude_code/README.md @@ -52,7 +52,7 @@ server means one set of background watchers / dream cron across all your Claude ## Install the plugin ``` -/plugin marketplace add ./plugins +/plugin marketplace add ./plugins/claude_code /plugin install reme@reme-marketplace ``` @@ -62,10 +62,10 @@ recall memory and report server health. ## Notes -- The plugin's MCP server URL lives in `plugins/reme/.mcp.json`. Keep it in sync with how you start +- The plugin's MCP server URL lives in `plugins/claude_code/reme/.mcp.json`. Keep it in sync with how you start ReMe (host/port). The Stop hook reads this same file to find the server (override with `REME_HOST` / `REME_PORT` env vars). - The Stop hook needs `python3` on `PATH` and resolves transcripts under `~/.claude/projects` - (override the base with `CLAUDE_CONFIG_DIR`). It logs to `plugins/reme/logs/auto_memory_hook.log`. + (override the base with `CLAUDE_CONFIG_DIR`). It logs to `plugins/claude_code/reme/logs/auto_memory_hook.log`. - The MCP tool-name prefix (`mcp__reme__…`) may include the server segment depending on your Claude Code version; the skill uses the `mcp__reme__*` wildcard so it works either way. diff --git a/skills/reme_memory/SKILL.md b/skills/reme_memory/SKILL.md index b4a7133c..3dd8e660 100644 --- a/skills/reme_memory/SKILL.md +++ b/skills/reme_memory/SKILL.md @@ -1,35 +1,138 @@ --- name: reme_memory -description: Use ReMe as a file-native long-term memory system through the reme CLI. +description: Set up and use ReMe as a file-native long-term memory system through the reme CLI. Use when an Agent needs to detect whether ReMe is installed or running, install and configure ReMe, start or verify its local service, retrieve prior context, or write and consolidate durable memory. --- -## ReMe Memory +# ReMe Memory -Use ReMe as the persistent memory layer for this Agent. ReMe stores raw sessions, daily notes, resources, and long-term digest memories in a local workspace. Prefer ReMe for information that should survive across conversations. +Use ReMe as the persistent memory layer for this Agent. ReMe stores raw sessions, daily notes, resources, and long-term +digest memories in a user-owned local workspace. -## Before Use +## Bootstrap ReMe -- ReMe should already be running with `reme start`. -- If a command fails because the service is not running, tell the user to start ReMe. -- Use CLI commands directly; do not edit the workspace files by hand unless the user explicitly asks. +Run this workflow before first use and whenever a ReMe command cannot reach the service. Distinguish a missing CLI from +an installed but stopped service. -Useful health checks: +### 1. Check whether ReMe is installed + +Run: + +```bash +command -v reme +``` + +If this prints an executable path, treat ReMe as installed and continue to service discovery. Do not reinstall or upgrade +an existing installation unless the user requests it. + +If the command is missing, check Python before installing: + +```bash +python3 -c 'import sys; print(sys.version); raise SystemExit(0 if sys.version_info >= (3, 11) else 1)' +``` + +ReMe requires Python 3.11 or newer. If the user has requested setup or installation, install the recommended package in +the active Python environment: + +```bash +python3 -m pip install "reme-ai[core]" +``` + +When working from a ReMe source checkout and the user explicitly wants an editable source installation, run this from +the repository root instead: + +```bash +python3 -m pip install -e ".[core]" +``` + +Do not silently install into or modify a Python environment when the user only asked to use memory. Explain that ReMe is +missing and ask before installing. After installation, run `command -v reme` again. If it is still missing, check that +the active environment's executable directory is on `PATH`; do not repeatedly reinstall. + +### 2. Configure optional model credentials + +Basic file operations, BM25 search, wikilink traversal, and reading existing proactive topics work without model +credentials. `auto_memory`, `auto_resource`, and `auto_dream` require an LLM configuration. + +When those model-powered jobs are needed, have the user provide valid values through the environment or a `.env` file: + +```dotenv +LLM_API_KEY=sk-xxx +LLM_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1 +``` + +The default LLM backend is OpenAI-compatible and the default model is `qwen3.7-plus`. Override them when the endpoint +requires different values: + +```dotenv +LLM_BACKEND=openai +LLM_MODEL_NAME=qwen3.7-plus +``` + +ReMe searches for `.env` in the directory where its command starts and up to five parent directories. Start the service +from a stable directory where the intended `.env` is discoverable. Never expose, log, or commit credentials. + +Embedding retrieval is disabled by default. Do not request `EMBEDDING_API_KEY` merely to use the default BM25 and +wikilink search. Enabling vector retrieval also requires changing the embedding components in ReMe's configuration; do +not claim that setting an embedding key alone enables it. + +### 3. Discover or start the service + +Check for an existing ReMe service before starting another one: ```bash reme find_reme -reme health_check -reme version ``` -## Retrieval +If it prints `HOST=... PORT=... PID=...`, reuse that service and its workspace. Do not start a duplicate or change its +workspace configuration. -Before answering questions about previous conversations, user preferences, project history, decisions, resources, or long-term context, search ReMe first: +If it reports `reme not started`, start ReMe in a persistent terminal or managed process and leave it running: + +```bash +reme start +``` + +The default HTTP address is `127.0.0.1:2333`, and the default workspace is `.reme/` under the startup directory. For +durable Agent memory, prefer a stable, user-selected workspace path so memory does not depend on the caller's current +directory: + +```bash +reme start workspace_dir="/absolute/path/to/reme-workspace" +``` + +If port `2333` is occupied, do not stop or replace the unknown listener. Start ReMe on another port: + +```bash +reme start workspace_dir="/absolute/path/to/reme-workspace" service.port=8181 +``` + +Keep the startup command and workspace choice consistent across restarts. ReMe CLI commands discover a locally running +ReMe process, including one started with a custom port. + +### 4. Verify readiness + +After the service starts, run these commands from another terminal or tool session: + +```bash +reme find_reme +reme version +reme health_check +``` + +Proceed only when `version` responds and `health_check` reports a healthy service. Use `reme list` to inspect the jobs +exposed by the running configuration. If verification fails, report the exact error and keep installation failure, +service discovery failure, port conflict, and missing model credentials as separate diagnoses. + +## Retrieve Memory + +Before answering questions about previous conversations, user preferences, project history, decisions, resources, or +long-term context, search ReMe first: ```bash reme search query="" limit=5 ``` -When search results point to a useful file, read the relevant file or range: +Read the relevant result rather than relying only on the search snippet: ```bash reme read path="" @@ -42,11 +145,15 @@ Use `traverse` when wikilink neighbors may matter: reme traverse path="" depth=1 direction=both ``` -## Writing Memory +Cite the workspace-relative paths used. If retrieval returns nothing useful, say so plainly instead of inventing prior +context. -Record memory when the conversation includes durable facts, user preferences, important decisions, project context, or lessons learned. Avoid storing secrets or sensitive personal data unless the user explicitly requests it. +## Write Memory -For ordinary conversation memory, call `auto_memory` with the current conversation messages and a stable session id: +Record durable facts, user preferences, important decisions, project context, and lessons learned. Avoid secrets or +sensitive personal data unless the user explicitly asks to store them. + +For an ordinary conversation, call `auto_memory` with the current messages and a stable session ID: ```bash reme auto_memory \ @@ -55,46 +162,57 @@ reme auto_memory \ memory_hint="" ``` -For direct file operations, use ReMe file jobs: +This job requires the LLM configuration described above. A missing LLM credential is not evidence that basic ReMe file +operations or BM25 retrieval are unavailable. + +For explicit file operations, read before editing and preserve existing content unless replacement is intended: ```bash reme write path="daily//.md" name="" description="" content="" reme edit path="" old="" new="" ``` -Read before editing, and preserve existing content unless replacing it is explicitly intended. +Use ReMe commands instead of editing memory files directly unless the user explicitly asks for direct file maintenance. -## Resources +## Ingest Resources -External documents should be placed under `resource/YYYY-MM-DD/`. ReMe background watchers normally process new resource files after `reme start`. +Place external documents under `resource/YYYY-MM-DD/` in the selected ReMe workspace. The default background watcher +processes supported new or changed files while `reme start` is running. -To trigger resource processing manually: +To request processing explicitly: ```bash reme auto_resource changes='[{"path":"resource//","change":"added"}]' ``` -## Long-Term Consolidation +`auto_resource` requires LLM credentials. -`auto_dream` consolidates daily notes and resource interpretations into long-term digest memories. It can run from cron in ReMe, or be called manually when the Agent framework owns the schedule: +## Consolidate and Use Proactive Topics + +The default service runs background and cron jobs while it remains active. `auto_dream` consolidates daily notes and +resource interpretations into long-term digest memory and generates interest topics. Run it manually when the host owns +the schedule or the user requests consolidation: ```bash reme auto_dream date="" ``` -Use `proactive` to read interest topics generated by `auto_dream`: +Read generated topics with: ```bash reme proactive date="" ``` -`proactive` returns structured topics and, by default, the source YAML content. Pass `include_content=false` when the raw -content is not needed. The Agent decides whether and how to mention the topics to the user. +`auto_dream` requires LLM credentials. `proactive` reads existing structured topics and works without an LLM call. Pass +`include_content=false` when raw YAML content is unnecessary. The host Agent decides whether and how to mention topics; +ReMe does not independently notify the user or take external action. ## Integration Rules -- Any Agent framework can integrate ReMe through this skill plus the `reme` CLI. -- Background and cron jobs run automatically after `reme start`. -- Hook jobs require explicit Agent lifecycle integration: call `auto_memory` after useful conversation turns, `auto_resource` after resource ingestion, `auto_dream` on a schedule or user request, and `proactive` before generating proactive suggestions. -- QwenPaw 2.0 will integrate the new ReMe flow directly. -- A Claude Code plugin is planned for lower-friction setup. +- Reuse a healthy running service; never start one ReMe process per command or conversation. +- Keep one stable workspace for contexts that should share memory. Use separate workspaces when profiles must be isolated. +- Call `auto_memory` after useful conversation turns only when the host owns lifecycle integration. +- Use ReMe's in-process `ReMe` Python API instead of the CLI when embedding it into a Python host application. +- Prefer the dedicated integrations under `plugins/claude_code/reme` and `plugins/hermes_agent` for those hosts. +- Treat user-owned memory files as source data. Do not delete, rewrite, or migrate a workspace merely to repair an index; + use rebuildable index operations such as `reme reindex` when appropriate.