From ab66f2bb56205c5753e55775417656db1bc774da Mon Sep 17 00:00:00 2001
From: jinliyl <6469360+jinliyl@users.noreply.github.com>
Date: Wed, 12 Aug 2026 10:59:03 +0800
Subject: [PATCH] docs: refresh ReMe guides, diagrams, and Studio documentation
(#447)
* docs: update ReMe documentation URL
* docs: localize ReMe Studio social image
* docs(AGENTS): update agent guidelines and repository documentation structure
- Clarify coding agent guidance for keeping changes small and consistent
- Revise project principle descriptions for clarity and modern terminology
- Expand repository map with detailed component and folder explanations
- Add configuration and CLI usage instructions, including syntax and merging rules
- Elaborate on component, step registration, and application lifecycle processes
- Define jobs, steps, and state handling conventions for stateless design
- Specify workspace and file safety policies, including path restrictions and locking
- Update validation commands and testing environment recommendations
- Clarify coding and test conventions, including style and dependency policies
- Distinguish documentation boundaries and update website content contribution notes
- Reinforce change guardrails to avoid breaking backward compatibility and data loss
- Improve svg diagram formatting and textual details in auto dream and proactive flow image
* style(docs): fix font-family syntax in SVG style definitions
- Correct quotation marks around font-family names in memory-as-file.svg
- Standardize font-family formatting by removing unnecessary quotes in reme-blog-architecture.svg
- Ensure consistent CSS style formatting within SVG files for better rendering fidelity
* docs: add ReMe blog to news
* style(docs): inline svg styles and improve text formatting
- Convert multiline SVG style tags into single-line for compactness in multiple figures
- Remove redundant line breaks in subtitle text elements for consistency
- Shorten descriptive texts in SVG figures for clarity and conciseness
- Adjust font sizes and text for better readability in SVG elements
- Correct whitespace issues in Chinese markdown document for improved formatting
- Remove unused style blocks from framework structure SVG for cleaner code
---
AGENTS.md | 266 +++++++-------
README.md | 169 ++++++---
README_ZH.md | 161 ++++++---
cookbook/auto-fin/README.md | 44 ++-
cookbook/auto-fin/README_ZH.md | 48 +--
cookbook/daily_paper/README.md | 61 ++--
cookbook/daily_paper/README_ZH.md | 73 ++--
docs/en/auto_dream.md | 129 ++++---
docs/en/auto_link.md | 99 +++---
docs/en/auto_memory.md | 51 +--
docs/en/auto_resource.md | 46 +--
docs/en/contributing.md | 67 ++--
docs/en/framework.md | 263 +++++++-------
docs/en/memory_as_file.md | 153 ++++----
docs/en/memory_search.md | 86 +++--
docs/en/proactive.md | 60 ++--
docs/en/quick_start.md | 39 +-
docs/en/reme-blog.md | 30 +-
docs/en/reme_scene.md | 34 +-
docs/figure/auto-dream-and-proactive.svg | 226 ++++++------
docs/figure/auto-index-and-memory-search.svg | 166 ++++-----
docs/figure/auto-memory-resource.svg | 154 ++++----
docs/figure/design-philosophy.svg | 166 ++++-----
docs/figure/framework-structure.svg | 279 +++++++--------
docs/figure/memory-as-file.svg | 183 +++++-----
.../reme-blog/reme-blog-architecture.svg | 121 ++++---
.../figure/reme-blog/reme-blog-auto-dream.svg | 170 ++++-----
.../reme-blog/reme-blog-auto-memory.svg | 84 +++--
.../reme-blog/reme-blog-auto-resource.svg | 138 ++++----
.../reme-blog/reme-blog-cover-benchmark.svg | 75 ++--
.../reme-blog/reme-blog-memory-as-file.svg | 21 +-
.../reme-blog/reme-blog-memory-index.svg | 100 +++---
.../reme-blog/reme-blog-memory-search.svg | 87 +++--
docs/figure/reme-blog/reme-blog-proactive.svg | 92 +++--
docs/figure/reme-overview.svg | 334 ++++++++----------
docs/zh/auto_dream.md | 87 +++--
docs/zh/auto_link.md | 49 +--
docs/zh/auto_memory.md | 41 ++-
docs/zh/auto_resource.md | 25 +-
docs/zh/contributing.md | 18 +-
docs/zh/framework.md | 206 ++++++-----
docs/zh/memory_as_file.md | 95 ++---
docs/zh/memory_search.md | 49 ++-
docs/zh/proactive.md | 40 +--
docs/zh/quick_start.md | 25 +-
docs/zh/reme-blog.md | 28 +-
docs/zh/reme_scene.md | 36 +-
.../reme/.claude-plugin/plugin.json | 2 +-
pyproject.toml | 2 +-
skills/reme_memory/SKILL.md | 17 +-
website/README.md | 61 +++-
website/README_ZH.md | 85 +++++
website/public/og.png | Bin 1354150 -> 1605927 bytes
53 files changed, 2864 insertions(+), 2277 deletions(-)
create mode 100644 website/README_ZH.md
diff --git a/AGENTS.md b/AGENTS.md
index f1bc7da7..e4065fba 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,20 +1,19 @@
# AGENTS.md
-This file guides coding agents working in the ReMe repository. Keep changes small,
-testable, and consistent with the contracts already expressed by the code.
+This file guides coding agents working in the ReMe repository. Keep changes small, testable, and consistent with the
+contracts expressed by the current code.
## Project Principles
ReMe is a local-first, file-native memory system for agents.
-- User-owned memory files are the source of truth.
-- Indexes, caches, metadata, and generated state must be rebuildable.
-- Prefer transparent formats and behavior over hidden state.
-- Preserve user control over storage, configuration, and service boundaries.
+- User-owned workspace files are the durable source of truth.
+- Indexes, catalogs, graphs, caches, and generated metadata must remain rebuildable.
+- Prefer transparent formats and predictable behavior over hidden state.
+- Preserve user control over workspace paths, configuration, and service boundaries.
- Keep concepts focused on project intent; let code and schemas describe implementation.
-When a proposed convenience conflicts with these principles, favor data ownership,
-recoverability, and predictable behavior.
+When convenience conflicts with these principles, favor data ownership, recoverability, and explicit behavior.
## Sources of Truth
@@ -22,166 +21,189 @@ Use this order when documentation and implementation disagree:
1. Current code and public Pydantic schemas.
2. Tests that describe supported behavior.
-3. CLI help and the built-in configuration.
-4. Development documentation and historical notes.
+3. CLI behavior and the built-in configuration.
+4. README files and other development documentation.
-Do not copy large implementation descriptions into documentation. Link to the relevant
-module or express the stable contract instead. If behavior changes intentionally, update
-the code, schema, tests, configuration, and concise documentation together as needed.
+Do not duplicate large implementation descriptions in documentation. Express the stable contract and link to the
+relevant module where useful. When behavior changes intentionally, update the implementation, schemas, tests, defaults,
+and concise documentation together.
## Repository Map
-- `reme/reme.py`: CLI entry point and client/server dispatch.
-- `reme/application.py`: application assembly, dependency ordering, and lifecycle.
-- `reme/components/application_context.py`: application-wide wiring and shared in-memory metadata.
-- `reme/components/runtime_context.py`: scratch state shared by steps within one execution.
-- `reme/config/default.yaml`: built-in jobs, components, and defaults.
-- `reme/schema/`: public and runtime Pydantic contracts.
-- `reme/components/`: services, stores, clients, jobs, and component registration.
-- `reme/steps/`: executable job steps.
-- `tests/unit/`: primary fast validation suite.
-- `tests/integration/`: tests that may require real credentials or services.
-- `tests/vector/` and `tests/light/`: specialized suites.
-- `plugins/reme/`: Claude Code integration.
-- `skills/reme_memory/`: skill that communicates with the ReMe service.
-- `skills/qwenpaw_memory/`: separate direct-file memory convention; it does not call ReMe.
-- `docs/`: pages and assets that support the repository README; not the deployed docs site.
+- `reme/reme.py`: CLI entry point; dispatches `start`, `find_reme`, and client calls.
+- `reme/application.py`: application assembly, dependency ordering, job execution, and lifecycle.
+- `reme/config/config_parser.py`: YAML/JSON loading, environment expansion, dot-notation parsing, and deep config
+ merging.
+- `reme/config/default.yaml`: default service, jobs, steps, and components. Other files in
+ `reme/config/` are named configuration variants.
+- `reme/schema/application_config.py`: typed application, component, and job configuration.
+- `reme/schema/`: request, response, streaming, memory, graph, and file contracts.
+- `reme/components/application_context.py`: application-wide wiring and in-memory shared state.
+- `reme/components/runtime_context.py`: request-scoped data, response, streaming queue, and stop event.
+- `reme/components/base_component.py`: component lifecycle, dependency binding, and workspace helpers.
+- `reme/components/component_registry.py`: the process-wide `(component type, backend)` registry.
+- `reme/components/job/`: base, stream, background, and cron job implementations.
+- `reme/components/service/`: local CLI, HTTP, and MCP service backends.
+- `reme/components/`: agent wrappers, model adapters, stores, catalogs, graphs, indexes, clients, tokenizers, and
+ outbound proxies.
+- `reme/steps/`: registered job steps grouped by common, file I/O, index, evolve, cookbook, benchmark, and transfer
+ concerns.
+- `reme/utils/`: shared utilities, including service discovery, logging, web-static resolution, session I/O, token
+ accounting, and wikilink handling.
+- `tests/unit/`: primary fast, isolated validation suite.
+- `tests/integration/`: service/model tests that may need credentials or external processes.
+- `website/`: ReMe Workspace frontend source; its static build can be served by the HTTP service.
+- `plugins/claude_code/` and `plugins/hermes_agent/`: agent integrations.
+- `skills/`: standalone skills; `reme_memory` calls ReMe, while other skills may use separate tools or direct-file
+ conventions.
+- `benchmark/` and `cookbook/`: runnable evaluation and example workflows.
+- `docs/`: README-linked supporting pages and figures.
## Development Setup
-ReMe requires Python 3.11 or newer.
+ReMe requires Python 3.11 or newer. Install the editable development environment with:
```bash
pip install -e ".[dev,core]"
```
-Before changing behavior, inspect the adjacent implementation, schemas, configuration,
-and focused tests. Follow existing patterns unless the task explicitly calls for a new
-contract or architecture.
+Before changing behavior, inspect the adjacent implementation, schema, built-in config, and focused tests. Follow
+existing async and typing patterns unless the task explicitly requires a new contract.
-## Change Workflow
+## Configuration and CLI Contracts
-1. Identify the narrowest supported contract affected by the request.
-2. Read the relevant implementation and tests before editing.
-3. Make the smallest coherent change; avoid unrelated cleanup.
-4. Update related schemas, defaults, registrations, and imports when required.
-5. Add or adjust focused tests for observable behavior.
-6. Run proportionate validation and report anything not run.
+- CLI syntax is `reme ACTION key=value ...`; leading `-` or `--` on arguments is accepted.
+- Nested overrides use dot notation. Values support null, booleans, numbers, JSON collections, and quoted JSON strings;
+ leading-zero numeric-looking values remain strings.
+- `config=` loads a discovered config name or a `.yaml`, `.yml`, or `.json` file. With no explicit config
+ path, `default` is loaded when available.
+- Config files expand `${VAR}` and `${VAR:-default}` recursively. An undefined variable without a default is an error.
+- CLI/config overrides are deep-merged over the loaded file. Do not silently change this merge behavior or stable
+ configuration keys.
+- `ApplicationConfig` normalizes `workspace_dir` to an expanded absolute path. `session_dir`
+ must remain workspace-relative; standard transcripts live under `{session_dir}/dialog`.
+- `reme start` runs the configured service. `reme start job= ...` switches to the one-shot CLI service and runs
+ the job through the normal application lifecycle.
+- Other actions use a client selected from the running service configuration when discoverable, otherwise from local
+ config. Client-selection arguments must not leak into the job payload.
-Component and step discovery depends on registration imports:
+## Registration and Application Lifecycle
-- Components use `R.register(...)` in `reme/components/component_registry.py`.
-- Component packages must be reachable through `reme/components/__init__.py`.
-- Step modules must be reachable through `reme/steps/__init__.py`.
+Component and Step discovery is import-driven:
-Adding an implementation without its registration import can leave it undiscoverable at
-runtime. Treat the implementation, registry entry, and import side effect as one change.
+- Implementations declare a non-`BASE` `component_type` and register with `@R.register("backend")`
+ or `R.register(Class, "backend")`.
+- Component packages must be imported through `reme/components/__init__.py`.
+- Step packages/modules must be reachable through their package `__init__.py` chain and ultimately
+ `reme/steps/__init__.py`.
+- Adding an implementation without its registration import leaves it undiscoverable at runtime. Treat implementation,
+ registration, import side effect, defaults, and tests as one change.
-Do not silently change stable CLI flags, configuration keys, workspace layouts, serialized
-schemas, or service interfaces. When such a change is required, preserve compatibility
-where practical and make the migration explicit.
+`Application` validates config through `ApplicationContext`, creates workspace directories, instantiates the service,
+configured components, and jobs, and then manages lifecycle as follows:
-## Step State Model
+- Components start in topological dependency order. Missing required dependencies and cycles fail explicitly; optional
+ dependencies may resolve to `None`.
+- Jobs start after components in this order: base jobs, stream jobs, background jobs, then cron jobs.
+- Shutdown closes everything in reverse start order and then shuts down the optional thread pool.
+- If startup fails, already-started resources are closed.
+- `BaseComponent.start()` and `close()` are lock-protected and idempotent. Dependencies created by a standalone
+ `default_factory` are owned and closed by the parent component.
-Treat every Step as stateless. `BaseJob` stores Step specifications and builds fresh Step
-instances for each Job invocation. A Step instance must not use `self` or class variables to
-retain mutable runtime state between calls.
+Keep async clients, tasks, executors, and services under this lifecycle. Do not introduce an untracked long-lived
+resource.
-Place state according to its lifetime:
+## Jobs, Steps, and State
-- Constructor fields on `self`: immutable Step configuration and resolved dependencies only.
-- `self.context` (`RuntimeContext`): request data and intermediate results for one Job
- execution; sequential Steps share this context.
-- `self.app_context.metadata`: in-memory state that must be shared across Step or Job
- invocations for the lifetime of the Application.
-- Workspace files or a dedicated Component/store: durable state that must survive an
- Application restart.
+`BaseJob` resolves configured Step classes during job startup and constructs fresh Step instances for every invocation.
+Job-level kwargs are merged into each `RuntimeContext`, with call-time kwargs taking precedence. Sequential Steps in one
+invocation share the same `RuntimeContext` and `Response`.
-Use narrow, namespaced keys in `app_context.metadata`, following existing patterns such as
-`tool_contexts`. The ApplicationContext is shared, so account for
-concurrent access when values are mutable. New Step code must not fall back to `self.kwargs`
-or another Step field to emulate shared state when `app_context` is absent; tests of shared
-state should construct an `ApplicationContext`. If shared state grows into a stable
-service-level contract or needs its own lifecycle, locking, or persistence, promote it to a
-typed ApplicationContext field or a dedicated Component instead of expanding an ad hoc
-metadata bucket.
+Treat Step instances as invocation-scoped:
-Do not use `Response.metadata` as a state store. It is request-scoped output for callers and
-diagnostics, distinct from `ApplicationContext.metadata`.
+- Constructor fields and `self.kwargs` hold Step configuration and resolved dependencies. They may be cached or adjusted
+ during that one invocation, but must not be relied on across Job calls.
+- `self.context.data` holds request inputs and intermediate values shared by sequential Steps.
+- `self.context.response.answer`, `success`, and `metadata` are request-scoped output. Because the same response travels
+ through the Step chain, later Steps may consume metadata produced earlier, but it is not application-lifetime or
+ durable storage.
+- `self.app_context.metadata` holds in-memory state shared across Job/Step invocations for the life of one
+ `Application`, such as counters, tool-context state, session maps, or locks.
+- Workspace files or a dedicated Component/store hold durable state that must survive restart.
+
+Use narrow, namespaced keys in `app_context.metadata` and protect shared mutable values against concurrent access. The
+search/draft helpers intentionally mirror tool-context state into
+`self.kwargs` only when no `ApplicationContext` exists for standalone use and unit tests; do not generalize that
+compatibility fallback into persistent runtime state. If shared state becomes a stable service contract or needs
+dedicated lifecycle, locking, or persistence, promote it to a typed context field or Component.
+
+Additional Step contracts:
+
+- `Ref` dependencies resolve in this order: Step kwargs, current `RuntimeContext`, then the named application component.
+ The value is cached only on the current Step instance and cleared before each call.
+- `input_mapping` and `output_mapping` copy keys within `RuntimeContext.data`; missing sources are ignored.
+- Dispatched Steps receive the current `RuntimeContext`, so their data and response are shared.
+- Base jobs convert uncaught Step errors into `Response(success=False)`; stream jobs emit an error chunk and always a
+ terminal `DONE`; background jobs let errors reach their supervisor.
+- Background jobs are never service-exposed. MCP also skips stream jobs. Respect `enable_serve`
+ and any configured service job allowlist.
+
+## Workspace and File Safety
+
+- Application startup creates the workspace plus configured metadata, session, memory-session, resource, daily, and
+ digest directories.
+- File-operation paths are resolved against the workspace and must stay inside it. Home-relative paths are unsupported,
+ traversal escapes are rejected, and `_allowed_paths` restrictions fail closed when invalid.
+- Preserve per-path locking, encoding detection, byte limits, truncation behavior, and optimistic
+ `expected_mtime` checks when modifying file operations.
+- Do not bypass the existing file steps or stores in a way that weakens workspace containment.
+- Never write test state into the repository's `.reme/`; use `tmp_path` or another isolated workspace.
+- Do not delete or rewrite user memory to repair an index or make a test pass. Rebuild derived state from source files
+ instead.
## Validation
Use the narrowest useful check while iterating, then broaden it according to risk.
-Run a focused test:
+Focused test:
```bash
pytest tests/unit/path/to/test_file.py -v
```
-Run the main unit suite:
+Main unit suite:
```bash
pytest tests/unit -v --tb=long -s --log-cli-level=WARNING
```
-Run repository formatting and lint checks when the change warrants it:
+Repository formatting and lint checks:
```bash
pre-commit run --all-files
```
-Formatting and lint configuration is authoritative. Python code currently uses a maximum
-line length of 120 for Black and Flake8, with Pylint also run by pre-commit.
+Black and Flake8 use a 120-character line limit and Python 3.11 formatting; Pylint is also run by pre-commit. If
+`website/` changes, use its Node 22.13+ scripts and run the proportionate checks from that directory, such as
+`npm run format:check`, `npm run lint`, or `npm test`.
-Integration tests may contact real services and require credentials such as
-`LLM_API_KEY` or `EMBEDDING_API_KEY`. Do not run credentialed or externally mutating tests
-automatically. Run them only when the task requires them and the user has supplied or
-authorized the necessary environment.
+Integration tests may contact real model providers, services, or agent subprocesses and can require credentials. Do not
+run credentialed or externally mutating tests automatically; run them only when the task requires them and the necessary
+environment has been supplied or authorized. Mock network, model, and subprocess boundaries in unit tests.
-## Coding and Test Conventions
-
-- Target Python 3.11+ and follow the surrounding typing and async style.
-- Steps are stateless. If a step needs to persist state, store it in
- `self.app_context.metadata` rather than on the step instance.
-- Keep public schemas explicit and backward-compatible where practical.
-- Close async clients, services, tasks, and other lifecycle resources deterministically.
-- Prefer clear failures over silently falling back to corrupt or ambiguous state.
-- Keep indexes and caches derivable from user-owned source files.
-- Use `tmp_path` or another isolated temporary workspace in tests.
-- Never write test state into the repository's `.reme/` directory.
-- Mock network or model boundaries in unit tests.
-- Do not commit `.env` files, credentials, runtime memory, logs, indexes, or caches.
-
-## Documentation Boundaries
-
-ReMe's local docs and the deployed documentation site have separate responsibilities.
-
-- Keep `docs/` focused on content and assets used by `README.md` and `README_ZH.md`.
-- Preserve README-linked pages under `docs/en/` and `docs/zh/`, including their relative
- paths, unless the README is updated in the same change.
-- Keep README-required images under `docs/figure/`.
-- Keep the README's main documentation index pointed at `docs.agentscope.io` or the
- `agentscope-ai/docs` repository, following the existing link style.
-- Do not treat local README-supporting pages as the source for the deployed website.
-
-The separate `agentscope-ai/docs` repository owns website content, navigation, versioning,
-and deployment. Public ReMe pages live there under `reme//`. Make website changes
-in that repository and follow its existing version-management conventions.
-
-Do not add website build configuration or deployment workflows to ReMe unless the task
-explicitly changes this repository boundary.
-
-## Agent Guardrails
+## Change Guardrails
- Preserve unrelated user changes in a dirty working tree.
-- Do not edit generated output when the source can be changed instead.
-- Do not delete or rewrite user data to make a test pass.
-- Avoid broad refactors unless they are necessary for the requested outcome.
-- Do not introduce dependencies without a concrete need and repository-level justification.
-- Treat network access, real credentials, and external service mutations as opt-in.
-- State which validations passed and which were not run in the final handoff.
+- Make the smallest coherent change and avoid unrelated cleanup or broad refactors.
+- Do not edit generated output when the source can be changed instead. The publish workflow builds
+ `website/dist-static` and copies it into `reme/web`; change `website/` source for frontend work.
+- Do not silently change CLI flags, configuration keys, workspace layouts, serialized schemas, endpoint shapes,
+ streaming termination, or service interfaces. Preserve compatibility where practical and document intentional
+ migrations.
+- Do not introduce dependencies without a concrete repository-level need.
+- Do not commit `.env` files, credentials, runtime memory, logs, indexes, caches, benchmark outputs, or generated
+ website distributions.
+- State which validations passed and which relevant checks were not run in the final handoff.
-If a requirement is ambiguous, first infer intent from nearby code, tests, and schemas. Ask
-the user only when the remaining choice would materially alter a public contract, user data,
-or external system.
+If a requirement is ambiguous, infer intent from nearby code, schemas, defaults, and tests. Ask the user only when the
+remaining choice would materially alter a public contract, user data, or an external system.
diff --git a/README.md b/README.md
index dc1cc4d4..816b0dec 100644
--- a/README.md
+++ b/README.md
@@ -20,26 +20,28 @@
- An agent memory layer that turns conversations and resources into readable, editable, searchable Markdown memory.
+ A local-first, self-evolving personal knowledge base for AI agents.
> Previous versions: [0.3.x](https://github.com/agentscope-ai/ReMe/tree/reme_v3) ·
> [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 is a local-first memory layer for **AI agents**. It turns conversations and resources into file-based long-term
-memory, then continuously indexes, links, and consolidates that memory for future recall.
+🧠 ReMe turns conversations and resources into readable, editable, searchable, and interconnected Markdown memory. It
+works alongside agents such as QwenPaw, OpenClaw, Hermes, and Claude Code, continuously organizing what they learn while
+keeping the files under the user's control.
## ✨ Core Ideas
-- **Memory as File**: Markdown files with frontmatter and wikilinks serve as memory nodes that both users and agents can
- read and write directly.
+- **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 long-term memories, while automatically building wikilink relationships.
+ 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, semantic recall, and relationship expansion.
+ 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 memory.
+ maintain, and reuse the same local workspace. HTTP, MCP, and Python integrations are also available.
@@ -59,8 +61,12 @@ memory, then continuously indexes, links, and consolidates that memory for futur
## 📰 News
-- [2026.08] - [Experience-driven enhancement method](benchmark/toolmemory/README.md) of agent tool-use
- execution built on ReMe is available on [arXiv:2608.03403](https://arxiv.org/abs/2608.03403).
+- [2026.08] - Published the [ReMe blog](docs/en/reme-blog.md), an end-to-end introduction to its local-first memory
+ architecture, self-evolving workflows, hybrid search, proactive discovery, and benchmark results.
+- [2026.08] - Introduced [ReMe Studio](website/README.md), a local web workspace for browsing, editing, and searching
+ memory files, chatting with the read-only ReMe Agent, inspecting the digest wikilink graph, and managing the local service.
+- [2026.08] - [Experience-driven enhancement method](benchmark/toolmemory/README.md) of agent tool-use execution built
+ on ReMe is available on [arXiv:2608.03403](https://arxiv.org/abs/2608.03403).
- [2026.07] - Introduced optional Cookbooks: [Daily Paper](cookbook/daily_paper/README.md) for paper discovery and
analysis, and [Auto Fin](cookbook/auto-fin/README.md) for researching the latest 24 hours of topic-related CLS news
with local-memory search and validated historical wikilinks.
@@ -128,15 +134,45 @@ reme start service.port=8181
After startup, check the service status. If you use a custom port, replace `2333` in the URL below with that port.
-The HTTP service also serves the bundled ReMe Workspace at when the web build is available.
-Set `service.web_enabled=false` to disable it, or use `service.web_static_dir` / `REME_WEB_STATIC_DIR` to provide a custom
-static build.
+When the web build is available, the HTTP service also serves **ReMe Studio** at . Studio can
+browse, edit, and search the workspace, chat with the read-only workspace agent, and inspect the digest wikilink graph.
+Set `service.web_enabled=false` to disable it, or use `service.web_static_dir` / `REME_WEB_STATIC_DIR` to provide a
+custom static build. The Job API remains available when no web build is found.
```bash
reme version
+reme health_check
+reme help
curl -s http://127.0.0.1:2333/version -H 'Content-Type: application/json' -d '{}'
```
+### Use ReMe Studio
+
+Open after starting the default HTTP service. Studio provides:
+
+- **Files, Daily, and Knowledge views** for navigating the whole workspace or focusing on `daily/` and `digest/`.
+- **Markdown tabs** with preview, split editing, optimistic save checks, and local download.
+- **Memory Graph** for exploring indexed `personal`, `procedure`, and `wiki` nodes and opening their Markdown sources.
+- **Read-only Agent chat** with streamed tool activity and usage; drag a workspace file into the composer to reference it.
+- **Settings** for service/component status, redacted effective configuration, version information, and safe index rebuilding.
+- English/Chinese language switching and light, dark, or system appearance.
+
+For frontend development, run ReMe and Studio in separate terminals:
+
+```bash
+# Terminal 1, repository root
+reme start
+
+# Terminal 2
+cd website
+npm install
+npm run dev
+```
+
+Then open . The development server uses `http://127.0.0.1:2333` by default; set
+`NEXT_PUBLIC_REME_API_URL` to connect to another ReMe HTTP service. Static-build and frontend configuration instructions are
+in the [ReMe Studio guide](website/README.md).
+
### 5-Minute Memory Demo
With the service running, write a memory node, let ReMe index it, then retrieve it:
@@ -171,6 +207,24 @@ ReMe stores agent memory as readable Markdown.
Related: [[digest/wiki/memory-as-file.md]]
```
+## 📚 Usage Guides
+
+These Markdown guides cover the main user workflows and the runtime contracts implemented by the current code.
+
+| Guide | What you will learn |
+|-------|---------------------|
+| [Quick Start](docs/en/quick_start.md) | Install ReMe, start the service, use Studio, 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 Studio](website/README.md) | Use, configure, develop, test, and build the web frontend. |
+| [ReMe Blog](docs/en/reme-blog.md) | Read the product story, design rationale, examples, and benchmark summary. |
+
## 🧑🍳 Cookbooks
Cookbooks are optional, end-to-end workflows assembled from ReMe jobs and steps. They are not enabled by the default
@@ -186,27 +240,33 @@ another row in this table.
> Memory as File, File as Memory.
-ReMe treats **memory as files**, progressively processing raw conversations and external resources from `session/` and
-`resource/` into `daily/`, then consolidating them into reusable long-term memory nodes under `digest/`.
+ReMe treats **memory as files**, progressively processing filtered conversation source records and external resources
+from `session/` and `resource/` into `daily/`, then consolidating them into reusable long-term memory nodes under
+`digest/`. The default workspace is `.reme/` under the current directory; `workspace_dir=...` selects a different
+user-owned location.
### Directory Structure
```text
/
-├── metadata/ # Persistent system state such as indexes, graphs, and catalogs
-├── session/ # Raw conversations and agent sessions
+├── metadata/ # Rebuildable indexes, graphs, catalogs, and caches
+├── session/ # Conversation source records and agent sessions
│ ├── dialog/
-│ │ └── .jsonl
-│ ├── agentscope/
+│ │ └── .jsonl # Source messages saved by auto_memory
│ └── claude_code/
+│ └── .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
+│ ├── . # Root-level files enter today's daily layer
│ └── YYYY-MM-DD/
│ └── .
├── daily/ # Lightly processed memory: daily facts, conversation summaries, resource readings
│ ├── YYYY-MM-DD.md
│ └── YYYY-MM-DD/
-│ ├── .md
-│ ├── .md
+│ ├── .md # Topic-named conversation or resource card
│ └── interests.yaml
└── digest/ # Long-term memory: personal facts, procedural experience, knowledge nodes
├── personal/
@@ -223,23 +283,24 @@ ReMe treats **memory as files**, progressively processing raw conversations and
## 🧭 Memory Design Philosophy
-> Capture raw dialogs and resources, refine them into long-term preferences, reusable experience, and valuable
-> knowledge,
+> Capture conversation source records and resources, refine them into long-term preferences, reusable experience, and
+> valuable knowledge,
> while keeping the result editable by humans and agents.
### Automatic Memory Flow
ReMe follows a capture → index → consolidate → recall loop. Conversations and resources first become daily memory cards;
background jobs keep files searchable; `auto_dream` distills stable knowledge into `digest/`; agents recall memory
-through search, wikilinks, or proactive topics.
+through search, wikilinks, or proactive topics. The files are the durable source of truth—indexes, graphs, catalogs, and
+caches under `metadata/` can be rebuilt from them.
-| 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 the raw session. | `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 daily cards. | `daily//.md` |
-| [`auto_index`](docs/en/memory_search.md) | Background watcher or `reme reindex` | Maintains chunks, the BM25 index, the wikilink graph, and the optional embedding index. | Searchable `daily/`, `digest/`, and `resource/` content |
-| [`auto_dream`](docs/en/auto_dream.md) | `dream_cron` or `reme auto_dream` | Consolidates changed daily cards into long-term personal, procedure, and wiki memory. | `digest/**`, `daily//interests.yaml` |
-| [`proactive`](docs/en/proactive.md) | `reme proactive` before an agent decides to act | Reads topics generated by `auto_dream`; the host agent decides whether and how to mention them. | Structured topics from `daily//interests.yaml` |
+| 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 |
+| [`auto_dream`](docs/en/auto_dream.md) | `dream_cron` or `reme auto_dream` | By default, extracts up to five reusable units from changed files in the latest two-day window, then creates, corroborates, refines, or corrects digest nodes. | `digest/**`, `daily//interests.yaml` |
+| [`proactive`](docs/en/proactive.md) | `reme proactive` before an agent decides to act | Reads topics generated by `auto_dream`; the host agent decides whether and how to mention them. | Structured topics from `daily//interests.yaml` |
@@ -260,18 +321,44 @@ through search, wikilinks, or proactive topics.
+Search returns the best matching chunks with file paths and line ranges, then lists bounded incoming and outgoing
+wikilink neighbors by metadata. An agent can read a promising source or traverse the graph only when needed. With
+embeddings enabled, BM25 and vector rankings are fused with reciprocal rank fusion (RRF); otherwise the default remains
+BM25 plus wikilink expansion.
+
+> [!IMPORTANT]
+> `proactive` only reads and exposes interest topics produced by Auto Dream. It does not independently browse the web,
+> send notifications, or rewrite the knowledge base; the host agent decides whether and how to act on a topic.
+
+## 📊 Performance
+
+ReMe evaluates multi-session and long-context memory with agentic search-and-read workflows. The figures below are the
+published reference runs in this repository; model, prompt, dataset, and judging details are documented with each
+benchmark.
+
+| Benchmark | Setting | Sample size | Agentic score | Focus |
+|--------------------------------------------------------------|--------------|-------------------------:|--------------:|--------------------------------------------------------------------|
+| **[LongMemEval cleaned-s](benchmark/longmemeval/README.md)** | **Overall** | **500 questions** | **89.4%** | Cross-session retrieval, knowledge updates, and temporal reasoning |
+| [BEAM](benchmark/beam/README.md) | 100K context | 20 cases / 400 questions | 66.1% | Ten types of long-context memory tasks |
+| [BEAM](benchmark/beam/README.md) | 1M context | 35 cases / 700 questions | 65.0% | Ultra-long conversation settings |
+
+ReMe also achieved a **0.580 PROC score across five user personas** in the repository's
+[π-Bench evaluation](benchmark/pibench/README.md), 2.4% above NanoBot under the same test-model configuration. PROC
+measures proactive handling of hidden intent, clarification, cross-session preferences and conventions, task
+dependencies, and underspecified requests.
+
## 🤝 Agent-friendly Integration
ReMe can run as a local memory service accessed through the CLI, HTTP API, or MCP server, or it can be embedded in the
-host process through its Python API. Agents can choose the path that fits their runtime and share a local memory workspace
-when appropriate.
+host process through its Python API. The default HTTP service can serve ReMe Studio at the same address. Agents can
+choose the path that fits their runtime and share a local memory workspace when appropriate.
-| 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. |
+| 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
@@ -314,6 +401,8 @@ are mainly for maintenance, debugging, or advanced integration. Run `reme help`
| `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 auto_memory` | Turn conversation messages into daily memory cards. Requires LLM credentials. |
| `reme auto_resource` | Interpret files under `resource/` into daily resource cards. Requires LLM credentials. |
| `reme auto_dream` / `reme proactive` | Consolidate daily memory into long-term digest and surface topics worth attention. |
@@ -349,7 +438,7 @@ Thanks to everyone who has contributed to ReMe:
@software{ReMe2026,
title = {Remember me, Refine me: Memory Management Kit for Agents},
author = {ReMe Team},
- url = {https://reme.agentscope.io},
+ url = {https://docs.agentscope.io/reme},
year = {2026}
}
```
diff --git a/README_ZH.md b/README_ZH.md
index 1e61d447..1add2f23 100644
--- a/README_ZH.md
+++ b/README_ZH.md
@@ -20,22 +20,23 @@
@@ -300,6 +379,8 @@ frontmatter 和文件操作接口主要用于维护、调试或高级集成。
| `reme status` | 查看有状态数据组件的内存估算及进程 RSS。 |
| [`reme search`](docs/zh/memory_search.md) | 默认使用 BM25 和 wikilink 检索,启用后增加向量检索。 |
| `reme read` / `reme write` / `reme edit` | 检查和维护 Markdown 记忆文件。 |
+| `reme traverse` / `reme graph_snapshot` | 浏览 wikilink 邻域或按类别组织的 digest 图。 |
+| `reme chat` | 与可感知 workspace 的只读 Agent 进行流式对话;需要 LLM 凭证。 |
| `reme auto_memory` | 将对话 messages 转为 daily 记忆卡片;需要 LLM 凭证。 |
| `reme auto_resource` | 将 `resource/` 下的文件解读为 daily 资料卡片;需要 LLM 凭证。 |
| `reme auto_dream` / `reme proactive` | 将 daily 记忆整理为长期 digest,并暴露值得关注的主题。 |
@@ -333,7 +414,7 @@ frontmatter 和文件操作接口主要用于维护、调试或高级集成。
@software{ReMe2026,
title = {Remember me, Refine me: Memory Management Kit for Agents},
author = {ReMe Team},
- url = {https://reme.agentscope.io},
+ url = {https://docs.agentscope.io/reme},
year = {2026}
}
```
diff --git a/cookbook/auto-fin/README.md b/cookbook/auto-fin/README.md
index b81ea59b..f8ec45c8 100644
--- a/cookbook/auto-fin/README.md
+++ b/cookbook/auto-fin/README.md
@@ -2,9 +2,11 @@
[中文](README_ZH.md)
-Auto Fin fetches the latest 24 hours of CLS telegraph news, selects items related to configured topics, searches ReMe
-for useful historical context, and writes one Chinese Markdown report with validated wikilinks. Current news and topic
-selection stay in runtime memory; only the final report becomes durable memory.
+Auto Fin fetches a rolling window of CLS telegraph news (24 hours by default), selects items related to configured
+topics, searches ReMe for useful historical context, and writes one Chinese Markdown report with validated wikilinks.
+Current news and topic selection stay in runtime memory; only the final report becomes durable memory. The
+implementation lives in [`reme/steps/cookbook/auto_fin/`](../../reme/steps/cookbook/auto_fin/) and is assembled by
+[`daily_cookbook.yaml`](../../reme/config/daily_cookbook.yaml).
> Auto Fin has no reliable market-price feed. It does not calculate returns, targets, or entry points and is not
> investment advice.
@@ -14,9 +16,14 @@ selection stay in runtime memory; only the final report becomes durable memory.
```bash
python -m pip install -e ".[core]"
export LLM_API_KEY="your-api-key"
+export LLM_MODEL_NAME="qwen3.7-plus"
+export LLM_BASE_URL="https://your-provider.example/v1"
reme start config=daily_cookbook job=auto_fin
```
+`LLM_MODEL_NAME` defaults to `qwen3.7-plus`. There is no built-in `LLM_BASE_URL`, so set the OpenAI-compatible endpoint
+required by the selected provider.
+
The default topics are `黄金,机器人,半导体`. Override them per run:
```bash
@@ -45,27 +52,29 @@ daily/YYYY-MM-DD/auto_fin.md
stops only after covering the exact preceding 24 hours. Requests are rate-limited and retried; malformed records and
records outside the window are discarded.
-`auto_fin_topic_step` receives batches of current news and returns only related `news_id` values. Code rejects unknown
-or duplicate IDs. If nothing is relevant, the job succeeds as a skip without writing or sending a report.
+`auto_fin_topic_step` receives batches of current news and returns only related `news_id` values. Code ignores unknown
+IDs and deduplicates repeated IDs, then preserves the source-news order. If nothing is relevant, the job succeeds as a
+skip without writing or sending a report.
`auto_fin_merge_step` receives only selected current news. It exposes `memory_search` and `read`, instructs the Agent to
-search no later than yesterday, and keeps current CLS IDs, times, and titles as plain evidence. Only historical
-workspace Markdown may appear as wikilinks. Code rejects missing, absolute, escaping, backslash, and self-referential
-targets, degrading invalid links to their readable aliases.
+search no later than yesterday, and keeps current CLS IDs, times, and titles as plain evidence. The prompt limits
+wikilinks to historical Markdown actually used by the Agent; the code-level boundary independently keeps only existing,
+workspace-relative Markdown targets. Missing, absolute, escaping, backslash, and self-referential targets are degraded
+to their readable aliases.
Same-day reruns use the existing report as context and replace it with the revised result. The final write is atomic and
refreshes the daily index. No JSONL, intermediate Markdown, or structured Agent output is written.
## Parameters
-| Parameter | Default | Purpose |
-|---|---:|---|
-| `date` | `""` | Empty uses today in Shanghai; an explicit value must equal today |
-| `now` | `""` | Optional ISO 8601 decision time for testing or replay |
-| `topics` | `"黄金,机器人,半导体"` | Comma-separated topics; empty also uses these defaults |
-| `window_hours` | `24` | Rolling number of hours of CLS telegraph news to fetch; must be positive |
-| `request_interval` | `10` | Minimum delay in seconds after every CLS request attempt; may be zero |
-| `max_retries` | `3` | Maximum attempts for each CLS page request; must be at least one |
+| Parameter | Default | Purpose |
+|--------------------|-----------------------:|--------------------------------------------------------------------------|
+| `date` | `""` | Empty uses today in Shanghai; an explicit value must equal today |
+| `now` | `""` | Optional ISO 8601 decision time for testing or replay |
+| `topics` | `"黄金,机器人,半导体"` | Comma-separated topics; empty also uses these defaults |
+| `window_hours` | `24` | Rolling number of hours of CLS telegraph news to fetch; must be positive |
+| `request_interval` | `10` | Minimum delay in seconds after every CLS request attempt; may be zero |
+| `max_retries` | `3` | Maximum attempts for each CLS page request; must be at least one |
The built-in schedules run daily at 09:30, 11:30, and 18:00 in `Asia/Shanghai`.
@@ -77,7 +86,8 @@ reme_workspace/daily/YYYY-MM-DD/auto_fin.md
The report includes a title, description, current CLS evidence, historical analysis, contextual wikilinks, and a fixed
non-investment disclaimer. Network errors and invalid Agent output fail explicitly; no relevant current news is a
-successful skip.
+successful skip. If `DINGTALK_CONVERSATION_IDS` is empty, delivery is a no-op. If it is set, the DingTalk credentials
+described in the [Daily Paper cookbook](../daily_paper/README.md#6-dingtalk) are required.
## Validation
diff --git a/cookbook/auto-fin/README_ZH.md b/cookbook/auto-fin/README_ZH.md
index a823078b..0809ee50 100644
--- a/cookbook/auto-fin/README_ZH.md
+++ b/cookbook/auto-fin/README_ZH.md
@@ -2,9 +2,10 @@
[English](README.md)
-Auto Fin 自动拉取最近 24 小时的财联社电报,按配置 topics 筛选相关新闻,搜索 ReMe 中有回顾价值的历史材料,
-最后写入一份带校验 wikilink 的中文 Markdown 报告。当前新闻和筛选结果只存在于本次运行内存中,只有最终报告成为
-持久记忆。
+Auto Fin 自动拉取一个滚动时间窗口内的财联社电报(默认 24 小时),按配置 topics 筛选相关新闻,搜索 ReMe 中有回顾价值的历史材料,最后写入一份带校验
+wikilink 的中文 Markdown 报告。当前新闻和筛选结果只存在于本次运行内存中,只有最终报告成为持久记忆。实现位于
+[`reme/steps/cookbook/auto_fin/`](../../reme/steps/cookbook/auto_fin/),并由
+[`daily_cookbook.yaml`](../../reme/config/daily_cookbook.yaml) 装配。
> Auto Fin 没有可靠行情数据,不计算收益、目标价或买卖点,也不提供投资建议。
@@ -13,9 +14,13 @@ Auto Fin 自动拉取最近 24 小时的财联社电报,按配置 topics 筛
```bash
python -m pip install -e ".[core]"
export LLM_API_KEY="your-api-key"
+export LLM_MODEL_NAME="qwen3.7-plus"
+export LLM_BASE_URL="https://your-provider.example/v1"
reme start config=daily_cookbook job=auto_fin
```
+`LLM_MODEL_NAME` 默认是 `qwen3.7-plus`。代码没有内置 `LLM_BASE_URL`,请设置所选服务商提供的 OpenAI 兼容 endpoint。
+
默认 topics 是 `黄金,机器人,半导体`。可在运行时覆盖:
```bash
@@ -40,29 +45,29 @@ Research Agent 使用 memory_search + read 检索历史记忆
daily/YYYY-MM-DD/auto_fin.md
```
-`auto_fin_data_step` 使用财联社网页同源接口的签名和分页方式,从分析时刻开始向前翻页,直到完整覆盖严格的最近
-24 小时。请求带有限速和重试;损坏记录及窗口外记录会被丢弃。
+`auto_fin_data_step` 使用财联社网页同源接口的签名和分页方式,从分析时刻开始向前翻页,直到完整覆盖严格的最近 24
+小时。请求带有限速和重试;损坏记录及窗口外记录会被丢弃。
-`auto_fin_topic_step` 分批接收当前新闻,只返回相关的 `news_id`。代码拒绝未知 ID 并自动去重。如果没有相关
-新闻,Job 会成功跳过,不写报告也不发送通知。
+`auto_fin_topic_step` 分批接收当前新闻,只返回相关的 `news_id`。代码会忽略未知 ID、去除重复 ID,并保持源新闻顺序。如果没有相关新闻,Job
+会成功跳过,不写报告也不发送通知。
-`auto_fin_merge_step` 只接收筛选后的当前新闻,并向 Agent 开放 `memory_search` 和 `read`。历史检索截止到昨天;
-当前新闻以 CLS ID、时间和标题作为普通证据,只有历史 workspace Markdown 才能成为 wikilink。代码拒绝不存在、
-绝对路径、越界、反斜杠和自引用目标,无效链接会降级为可读 alias。
+`auto_fin_merge_step` 只接收筛选后的当前新闻,并向 Agent 开放 `memory_search` 和 `read`。历史检索截止到昨天;当前新闻以
+CLS ID、时间和标题作为普通证据。Prompt 要求 Agent 只链接实际使用过的历史 Markdown;代码边界则独立保证只保留真实存在、相对
+workspace 的 Markdown 目标。不存在、绝对路径、越界、带反斜杠和自引用的目标都会降级为可读 alias。
-同日重跑会参考当天已有报告并覆盖为修订结果。最终写入使用原子替换并刷新当天索引;流程不会写入 JSONL、
-中间 Markdown 或 Agent 结构化输出。
+同日重跑会参考当天已有报告并覆盖为修订结果。最终写入使用原子替换并刷新当天索引;流程不会写入 JSONL、中间 Markdown 或 Agent
+结构化输出。
## 参数
-| 参数 | 默认值 | 作用 |
-|---|---:|---|
-| `date` | `""` | 空值使用上海时区当天;显式日期必须等于当天 |
-| `now` | `""` | 测试或回放使用的 ISO 8601 分析时间 |
-| `topics` | `"黄金,机器人,半导体"` | 逗号分隔的主题;空值也使用这些默认值 |
-| `window_hours` | `24` | 向前抓取财联社电报的滚动小时数,必须大于 0 |
-| `request_interval` | `10` | 每次财联社请求尝试后的最小等待秒数,可设为 0 |
-| `max_retries` | `3` | 每页财联社请求的最大尝试次数,至少为 1 |
+| 参数 | 默认值 | 作用 |
+|--------------------|-----------------------:|----------------------------------------------|
+| `date` | `""` | 空值使用上海时区当天;显式日期必须等于当天 |
+| `now` | `""` | 测试或回放使用的 ISO 8601 分析时间 |
+| `topics` | `"黄金,机器人,半导体"` | 逗号分隔的主题;空值也使用这些默认值 |
+| `window_hours` | `24` | 向前抓取财联社电报的滚动小时数,必须大于 0 |
+| `request_interval` | `10` | 每次财联社请求尝试后的最小等待秒数,可设为 0 |
+| `max_retries` | `3` | 每页财联社请求的最大尝试次数,至少为 1 |
内置定时任务每天按 `Asia/Shanghai` 在 09:30、11:30 和 18:00 运行。
@@ -73,7 +78,8 @@ reme_workspace/daily/YYYY-MM-DD/auto_fin.md
```
报告包含标题、说明、当前 CLS 证据、历史分析、上下文 wikilink 和固定非投资建议声明。网络错误与无效 Agent 输出
-会明确失败;没有相关当前新闻则成功跳过。
+会明确失败;没有相关当前新闻则成功跳过。`DINGTALK_CONVERSATION_IDS` 为空时发送步骤无副作用;设置该变量后,
+还必须提供[每日论文 Cookbook](../daily_paper/README_ZH.md#6-dingtalk)中列出的钉钉凭据。
## 验证
diff --git a/cookbook/daily_paper/README.md b/cookbook/daily_paper/README.md
index b5b8d78d..25444f29 100644
--- a/cookbook/daily_paper/README.md
+++ b/cookbook/daily_paper/README.md
@@ -15,6 +15,8 @@ Hugging Face Papers and arXiv.
```bash
python -m pip install -e ".[core]"
export LLM_API_KEY="your-api-key"
+export LLM_MODEL_NAME="qwen3.7-plus"
+export LLM_BASE_URL="https://your-provider.example/v1"
reme start config=daily_cookbook job=daily_paper
```
@@ -79,8 +81,8 @@ A missing rank contributes zero. Papers are ordered by fused score, upvotes, and
```
All IDs must be unique and belong to the candidate pool, and every reason must be non-empty. A validation failure is
-returned to the agent for one retry. Only a non-empty `topics` value injects a personalized subject preference into
-the selection prompt; it does not change the fixed count of three papers.
+returned to the agent for one retry. Only a non-empty `topics` value injects a personalized subject preference into the
+selection prompt; it does not change the fixed count of three papers.
### 4. Analyze
@@ -99,9 +101,10 @@ the note records `pdf_text_truncated: true` in its frontmatter.
### 5. Digest
-`daily_paper_digest_step` uses the three in-memory analyses as the factual source for the Chinese brief. It also searches
-and, when needed, reads earlier daily notes to identify related coverage; those notes may only support contextual
-wikilinks, not add facts about the current papers. The agent returns `title`, `desc`, and `body`. The code then:
+`daily_paper_digest_step` uses the three in-memory analyses as the factual source for the Chinese brief. It also
+searches and, when needed, reads earlier daily notes to identify related coverage; those notes may only support
+contextual wikilinks, not add facts about the current papers. The agent returns `title`, `desc`, and `body`. The code
+then:
- strips model-generated YAML frontmatter if present;
- normalizes the Chinese title for use as a filename;
@@ -141,34 +144,36 @@ reme_workspace/
└── .pdf
```
-Filenames come from the agent's Chinese titles. The implementation removes unsafe path characters and resolves title
-collisions. Markdown and PDF outputs are written through same-directory temporary files and atomic replacement.
+Each successful generation writes three analysis notes and one brief. A forced rerun can leave unrelated or previously
+selected analysis notes in the same day directory; ReMe does not delete them as cleanup. Filenames come from the agent's
+Chinese titles. The implementation removes unsafe path characters and resolves title collisions. Markdown and PDF
+outputs are written through same-directory temporary files and atomic replacement.
## Parameters and defaults
Public job parameters:
-| Parameter | Default | Purpose |
-|---|---:|---|
-| `date` | `""` | Run date; empty uses today in the app timezone, otherwise requires `YYYY-MM-DD` |
-| `force` | `false` | Regenerate even when the day's brief exists |
+| Parameter | Default | Purpose |
+|-----------------|--------:|-----------------------------------------------------------------------------------------|
+| `date` | `""` | Run date; empty uses today in the app timezone, otherwise requires `YYYY-MM-DD` |
+| `force` | `false` | Regenerate even when the day's brief exists |
| `use_hf_mirror` | `false` | Use the Hugging Face mirror from `HF_MIRROR_URL`, or `https://hf-mirror.com` when unset |
-| `topics` | `""` | Topics to prioritize during selection |
-| `weekly_weight` | `0.7` | Weekly contribution to RRF |
-| `history_days` | `30` | Prior recommendation exclusion window |
+| `topics` | `""` | Topics to prioritize during selection |
+| `weekly_weight` | `0.7` | Weekly contribution to RRF |
+| `history_days` | `30` | Prior recommendation exclusion window |
Step-level settings on the `daily_paper` job:
-| Setting | Default | Purpose |
-|---|---:|---|
-| `candidate_limit` | `20` | Maximum candidates sent to Select |
-| `rrf_k` | `60` | RRF constant |
-| `hf_timeout` | `600` seconds | Timeout for one Hugging Face request |
-| `hf_max_retries` | `3` | Maximum Hugging Face attempts |
-| `pdf_timeout` | `600` seconds | arXiv PDF download timeout |
-| `max_pdf_bytes` | `52428800` | PDF limit, 50 MiB |
-| `max_pdf_pages` | `35` | Maximum extracted pages |
-| `max_pdf_chars` | `300000` | Maximum extracted PDF characters sent to the agent |
+| Setting | Default | Purpose |
+|-------------------|--------------:|----------------------------------------------------|
+| `candidate_limit` | `20` | Maximum candidates sent to Select |
+| `rrf_k` | `60` | RRF constant |
+| `hf_timeout` | `600` seconds | Timeout for one Hugging Face request |
+| `hf_max_retries` | `3` | Maximum Hugging Face attempts |
+| `pdf_timeout` | `600` seconds | arXiv PDF download timeout |
+| `max_pdf_bytes` | `52428800` | PDF limit, 50 MiB |
+| `max_pdf_pages` | `35` | Maximum extracted pages |
+| `max_pdf_chars` | `300000` | Maximum extracted PDF characters sent to the agent |
## Mirrors
@@ -183,7 +188,7 @@ DAILY_PAPER_USE_HF_MIRROR=true
# Read only when the manual or scheduled job enables the mirror; defaults to https://hf-mirror.com when unset
HF_MIRROR_URL=https://hf-mirror.com
-# Defaults to https://arxiv.org when unset
+# Optional override; the code defaults to https://arxiv.org when unset
ARXIV_MIRROR_URL=https://export.arxiv.org
# Path-prefixed relay URLs are also supported
@@ -237,11 +242,13 @@ curl -s http://127.0.0.1:8001/daily_paper \
## Failures and reruns
-- Hugging Face failures use exponential backoff up to `hf_max_retries` attempts.
+- Hugging Face HTTP failures use exponential backoff up to `hf_max_retries` attempts; invalid response payloads fail
+ immediately.
- Fewer than three candidates, invalid agent selection, invalid/oversized/textless PDFs, or empty agent output stop the
job.
- Papers are analyzed sequentially; PDFs and notes completed before a failure remain on disk.
-- `force=true` regenerates notes and the brief while reusing valid PDFs.
+- `force=true` regenerates the selected notes and the brief while reusing valid PDFs; it does not remove other notes
+ already present in that day's directory.
- The multi-file workflow is not transactional and has no global per-date execution lock.
## Tests
diff --git a/cookbook/daily_paper/README_ZH.md b/cookbook/daily_paper/README_ZH.md
index 72c78bcc..d6b9e0d6 100644
--- a/cookbook/daily_paper/README_ZH.md
+++ b/cookbook/daily_paper/README_ZH.md
@@ -13,6 +13,8 @@
```bash
python -m pip install -e ".[core]"
export LLM_API_KEY="your-api-key"
+export LLM_MODEL_NAME="qwen3.7-plus"
+export LLM_BASE_URL="https://your-provider.example/v1"
reme start config=daily_cookbook job=daily_paper
```
@@ -53,7 +55,8 @@ Collect ──► Rank ──► Select 3 篇 ──► Analyze PDF ──► Di
- 昨日 Daily Papers 中的论文;
- `history_days` 窗口内,已出现在 `daily//*.md` frontmatter `arxiv_id` 中的论文。
-如果当天已经存在 `kind: daily-paper-brief` 的 Markdown 且 `force=false`,整个生成流程会跳过;已有简报仍可进入钉钉发送步骤。没有剩余候选论文时,Job 直接失败。
+如果当天已经存在 `kind: daily-paper-brief` 的 Markdown 且 `force=false`,整个生成流程会跳过;已有简报仍可进入钉钉发送步骤。没有剩余候选论文时,Job
+直接失败。
### 2. Rank
@@ -74,7 +77,8 @@ score = 1 / (rrf_k + monthly_rank)
{"papers": [{"arxiv_id": "2601.01234", "reasoning": "具体且可核验的选择理由"}]}
```
-三个 ID 必须唯一且都属于候选池,理由不能为空。校验失败后,错误信息会反馈给 Agent 并重试一次。只有非空 `topics` 会向精选提示注入个性化主题,且不会改变固定的三篇数量。
+三个 ID 必须唯一且都属于候选池,理由不能为空。校验失败后,错误信息会反馈给 Agent 并重试一次。只有非空 `topics`
+会向精选提示注入个性化主题,且不会改变固定的三篇数量。
### 4. Analyze
@@ -87,12 +91,14 @@ score = 1 / (rrf_k + monthly_rank)
5. 将论文元数据、选择理由和 PDF 文本交给无工具 Agent;
6. 将中文解读写入 `daily//<中文标题>.md`。
-下载采用临时文件并在校验 PDF 文件头后原子替换,同时限制 `max_pdf_bytes`。当前没有 OCR;扫描版或无文本层 PDF 会失败。提取被截断时,笔记 frontmatter 中的 `pdf_text_truncated` 会记录为 `true`。
+下载采用临时文件并在校验 PDF 文件头后原子替换,同时限制 `max_pdf_bytes`。当前没有 OCR;扫描版或无文本层 PDF 会失败。提取被截断时,笔记
+frontmatter 中的 `pdf_text_truncated` 会记录为 `true`。
### 5. Digest
`daily_paper_digest_step` 以内存中的三篇解读作为本期事实来源生成中文简报,同时搜索并按需读取较早的 daily
-文章来识别相关报道;历史文章只能用于建立上下文 wikilink,不能用于补充本期论文事实。输出必须包含 `title`、`desc` 和 `body`。代码会:
+文章来识别相关报道;历史文章只能用于建立上下文 wikilink,不能用于补充本期论文事实。输出必须包含 `title`、`desc` 和 `body`
+。代码会:
- 去掉模型可能生成的 YAML frontmatter;
- 规范化中文标题并用作文件名;
@@ -130,37 +136,40 @@ reme_workspace/
└── .pdf
```
-文件名来自 Agent 返回的中文标题。代码会清理路径不安全字符,并处理同名文件。Markdown 和 PDF 都通过同目录临时文件写入后原子替换。
+每次成功生成会写入三篇论文解读和一篇简报。强制重跑后,当日目录中可能保留其他内容或此前入选论文的解读;ReMe
+不会把它们作为清理对象删除。文件名来自 Agent 返回的中文标题。代码会清理路径不安全字符,并处理同名文件。Markdown 和 PDF
+都通过同目录临时文件写入后原子替换。
## 参数与默认值
可在调用时传入的 Job 参数:
-| 参数 | 默认值 | 作用 |
-|---|---:|---|
-| `date` | `""` | 运行日期;空值使用应用时区当天,非空值必须为 `YYYY-MM-DD` |
-| `force` | `false` | 已有当日简报时仍重新生成 |
+| 参数 | 默认值 | 作用 |
+|-----------------|--------:|----------------------------------------------------------------------------------------------|
+| `date` | `""` | 运行日期;空值使用应用时区当天,非空值必须为 `YYYY-MM-DD` |
+| `force` | `false` | 已有当日简报时仍重新生成 |
| `use_hf_mirror` | `false` | 是否使用 Hugging Face 镜像站;优先读取 `HF_MIRROR_URL`,未配置时使用 `https://hf-mirror.com` |
-| `topics` | `""` | 精选论文时优先考虑的主题 |
-| `weekly_weight` | `0.7` | RRF 中周榜权重 |
-| `history_days` | `30` | 历史推荐排重窗口 |
+| `topics` | `""` | 精选论文时优先考虑的主题 |
+| `weekly_weight` | `0.7` | RRF 中周榜权重 |
+| `history_days` | `30` | 历史推荐排重窗口 |
`daily_paper` Job 的步骤级配置:
-| 配置 | 默认值 | 作用 |
-|---|---:|---|
-| `candidate_limit` | `20` | 送入 Select 的最大候选数 |
-| `rrf_k` | `60` | RRF 常数 |
-| `hf_timeout` | `600` 秒 | Hugging Face 单次请求超时 |
-| `hf_max_retries` | `3` | Hugging Face 最大尝试次数 |
-| `pdf_timeout` | `600` 秒 | arXiv PDF 下载超时 |
-| `max_pdf_bytes` | `52428800` | PDF 上限,50 MiB |
-| `max_pdf_pages` | `35` | 最多提取页数 |
-| `max_pdf_chars` | `300000` | 最多送入 Agent 的 PDF 字符数 |
+| 配置 | 默认值 | 作用 |
+|-------------------|-----------:|------------------------------|
+| `candidate_limit` | `20` | 送入 Select 的最大候选数 |
+| `rrf_k` | `60` | RRF 常数 |
+| `hf_timeout` | `600` 秒 | Hugging Face 单次请求超时 |
+| `hf_max_retries` | `3` | Hugging Face 最大尝试次数 |
+| `pdf_timeout` | `600` 秒 | arXiv PDF 下载超时 |
+| `max_pdf_bytes` | `52428800` | PDF 上限,50 MiB |
+| `max_pdf_pages` | `35` | 最多提取页数 |
+| `max_pdf_chars` | `300000` | 最多送入 Agent 的 PDF 字符数 |
## 镜像站
-数据客户端使用 httpx 默认的环境处理,因此存在 `HTTP_PROXY`、`HTTPS_PROXY` 或 `NO_PROXY` 时会自动生效。两个数据源启用镜像的方式不同:Hugging Face 由 `use_hf_mirror` 任务参数控制,arXiv 仅由环境变量驱动。
+数据客户端使用 httpx 默认的环境处理,因此存在 `HTTP_PROXY`、`HTTPS_PROXY` 或 `NO_PROXY` 时会自动生效。两个数据源启用镜像的方式不同:Hugging
+Face 由 `use_hf_mirror` 任务参数控制,arXiv 仅由环境变量驱动。
```dotenv
# 为内置 daily_paper_cron 定时任务启用镜像站
@@ -169,7 +178,7 @@ DAILY_PAPER_USE_HF_MIRROR=true
# 仅在手动任务或定时任务启用镜像时读取;未配置时使用 https://hf-mirror.com
HF_MIRROR_URL=https://hf-mirror.com
-# 未设置时使用 https://arxiv.org
+# 可选覆盖;未设置时代码使用 https://arxiv.org
ARXIV_MIRROR_URL=https://export.arxiv.org
# 也支持带路径前缀的中转地址
@@ -177,9 +186,13 @@ ARXIV_MIRROR_URL=https://export.arxiv.org
# ARXIV_MIRROR_URL=http://relay-host:18080/arxiv
```
-`HF_MIRROR_URL` 必须提供当前代码使用的 `/papers/...`、`/api/daily_papers` 和 `/api/papers/...` 路径。`ARXIV_MIRROR_URL` 必须支持 `/pdf/`。两种 base URL 都会保留路径前缀,末尾 `/` 可有可无。不存在备用地址回退:客户端选定哪个 base URL,就只访问该地址。
+`HF_MIRROR_URL` 必须提供当前代码使用的 `/papers/...`、`/api/daily_papers` 和 `/api/papers/...` 路径。`ARXIV_MIRROR_URL`
+必须支持 `/pdf/`。两种 base URL 都会保留路径前缀,末尾 `/` 可有可无。不存在备用地址回退:客户端选定哪个 base
+URL,就只访问该地址。
-> **行为变更:** 以往只要设置 `HF_MIRROR_URL` 就会改变 Hugging Face 的访问地址;现在该变量仅在任务启用镜像时才会读取,否则直接访问官方站点,并输出一条“已忽略该变量”的告警日志。手动调用需传入 `use_hf_mirror=true`,`daily_paper_cron` 定时任务需设置 `DAILY_PAPER_USE_HF_MIRROR=true`,才能继续走镜像。
+> **行为变更:** 以往只要设置 `HF_MIRROR_URL` 就会改变 Hugging Face
+> 的访问地址;现在该变量仅在任务启用镜像时才会读取,否则直接访问官方站点,并输出一条“已忽略该变量”的告警日志。手动调用需传入
+> `use_hf_mirror=true`,`daily_paper_cron` 定时任务需设置 `DAILY_PAPER_USE_HF_MIRROR=true`,才能继续走镜像。
## 运行方式
@@ -206,7 +219,9 @@ reme start config=daily_cookbook job=daily_paper date=2026-08-06 force=true
reme start config=daily_cookbook
```
-内置服务监听 `127.0.0.1:8001`,`daily_paper_cron` 按 `Asia/Shanghai` 时区每天 08:00 运行。设置 `DAILY_PAPER_USE_HF_MIRROR=true` 可让该定时任务使用 Hugging Face 镜像站。可通过 `DAILY_PAPER_HOST`、`DAILY_PAPER_PORT` 或启动参数覆盖监听地址和端口。
+内置服务监听 `127.0.0.1:8001`,`daily_paper_cron` 按 `Asia/Shanghai` 时区每天 08:00 运行。设置
+`DAILY_PAPER_USE_HF_MIRROR=true` 可让该定时任务使用 Hugging Face 镜像站。可通过 `DAILY_PAPER_HOST`、`DAILY_PAPER_PORT`
+或启动参数覆盖监听地址和端口。
```bash
curl -s http://127.0.0.1:8001/daily_paper \
@@ -216,10 +231,10 @@ curl -s http://127.0.0.1:8001/daily_paper \
## 失败与重跑
-- Hugging Face 请求失败会指数退避重试,最多尝试 `hf_max_retries` 次。
+- Hugging Face HTTP 请求失败会指数退避重试,最多尝试 `hf_max_retries` 次;响应数据格式无效时立即失败。
- 候选少于三篇、Agent 精选不合法、PDF 无效/过大/无文本或 Agent 输出为空都会终止 Job。
- 三篇论文按顺序处理;中途失败时,之前已完成的 PDF 和笔记会保留。
-- `force=true` 会重新生成笔记和简报,但会复用有效 PDF。
+- `force=true` 会重新生成本次入选论文的解读和简报,并复用有效 PDF;不会删除当日目录中已有的其他笔记。
- 多文件流程不是事务,也没有同一日期的全局运行锁。
## 测试
diff --git a/docs/en/auto_dream.md b/docs/en/auto_dream.md
index 749ebe46..bb6177f2 100644
--- a/docs/en/auto_dream.md
+++ b/docs/en/auto_dream.md
@@ -1,16 +1,17 @@
# Auto Dream
-`auto_dream` is ReMe's long-term memory distillation flow from daily to digest. It scans daily inputs for a specified date,
-processes only files that changed since the previous dream, extracts content worth retaining as memory units, integrates those
-units into `digest/`, and generates the day's `interests.yaml` for proactive use.
+`auto_dream` is ReMe's long-term memory distillation flow from daily to digest. By default it scans the target date and
+the previous day, processes only files changed since the previous dream, extracts a small set of high-value memory units
+across that window, integrates them into `digest/`, and writes the target day's `interests.yaml` for proactive use.
Its daily inputs usually come from [Auto Memory](./auto_memory.md) and [Auto Resource](./auto_resource.md). For the file
-semantics of `digest/`, Sources sections, and wikilinks, see [Memory as File](./memory_as_file.md). For the linking strategy
-used during Integrate, see [Auto Link](./auto_link.md). To read `interests.yaml`, use [Proactive](./proactive.md).
+semantics of `digest/`, Sources sections, and wikilinks, see [Memory as File](./memory_as_file.md). For the linking
+strategy used during Integrate, see [Auto Link](./auto_link.md). To read `interests.yaml`,
+use [Proactive](./proactive.md).
## Configuration
@@ -26,6 +27,12 @@ auto_dream:
hint:
type: string
default: ""
+ scan_days:
+ type: integer
+ default: 2
+ max_units:
+ type: integer
+ default: 5
topic_count:
type: integer
default: 3
@@ -36,6 +43,8 @@ auto_dream:
- backend: dream_extract_step
file_catalog: dream
topic_session_id: interests
+ scan_days: 2
+ max_units: 5
- backend: dream_integrate_step
- backend: dream_topics_step
topic_count: 3
@@ -46,34 +55,39 @@ auto_dream:
Parameters:
-| Parameter | Purpose |
-|---|---|
-| `date` | Date to process in `YYYY-MM-DD` format. When empty, use today in the application's timezone. |
-| `hint` | Additional guidance from the caller for the Extract and Integrate stages. |
-| `topic_count` | Maximum number of topics written to `interests.yaml`. Defaults to 3. |
+| Parameter | Purpose |
+|------------------------|---------------------------------------------------------------------------------------------------------|
+| `date` | Date to process in `YYYY-MM-DD` format. When empty, use today in the application's timezone. |
+| `hint` | Additional guidance from the caller for the Extract and Integrate stages. |
+| `scan_days` | Recent-date window ending at `date`; defaults to 2 and has a minimum of 1. |
+| `max_units` | Maximum reusable units extracted in one run; defaults to 5. |
+| `topic_count` | Maximum number of topics written to `interests.yaml`. Defaults to 3. |
| `topic_diversity_days` | Number of past days of `interests.yaml` files considered when avoiding duplicate topics. Defaults to 7. |
## Inputs and Outputs
-Inputs are daily Markdown files for the specified date:
+Inputs are daily Markdown files from the most recent `scan_days` ending at the specified date. For example,
+`date=2026-06-20` with `scan_days=2` scans:
```text
-daily/.md
-daily//**/*.md
+daily/2026-06-19.md
+daily/2026-06-19/**/*.md
+daily/2026-06-20.md
+daily/2026-06-20/**/*.md
```
-`daily//interests.yaml` is excluded from extraction input so topics from the previous run do not feed back into the
-next extraction.
+Every `daily//interests.yaml` in the scan window is excluded from extraction so previous proactive output cannot
+feed back into the next run. Final topics are written only for the target date.
The main outputs are:
-| Output | Description |
-|---|---|
-| `digest/procedure/*.md` | Methods, workflows, runbooks, and executable experience. |
-| `digest/personal/*.md` | User-, team-, and project-related preferences, facts, and long-term context. |
-| `digest/wiki/*.md` | General knowledge, concepts, observations, and decision precedents. |
-| `daily//interests.yaml` | Topics worth proactive attention from the host agent that day. |
-| `metadata/file_catalog/dream*` | Dream-specific catalog used to detect changes in daily inputs. |
+| Output | Description |
+|--------------------------------|------------------------------------------------------------------------------|
+| `digest/procedure/*.md` | Methods, workflows, runbooks, and executable experience. |
+| `digest/personal/*.md` | User-, team-, and project-related preferences, facts, and long-term context. |
+| `digest/wiki/*.md` | General knowledge, concepts, observations, and decision precedents. |
+| `daily//interests.yaml` | Topics worth proactive attention from the host agent that day. |
+| `metadata/file_catalog/dream*` | Dream-specific catalog used to detect changes in daily inputs. |
## Four Stages
@@ -81,43 +95,50 @@ The main outputs are:
`dream_extract_step` performs three tasks:
-1. Refresh the day's index page at `daily/.md`.
-2. Scan `daily/.md` and `daily//**/*.md` and compare their mtimes with `file_catalog: dream`.
-3. Send only changed files to the LLM and globally extract two structured result types: `units` and `topics`.
+1. Refresh each `daily/.md` in the scan window.
+2. Scan those day indexes and `daily//**/*.md`, comparing mtimes with `file_catalog: dream`.
+3. Send all changed files together to the LLM and globally extract two structured result types: `units` and `topics`.
`units` are long-term memory units ready to be distilled into digest. Each has `name`, `bucket`, `summary`, and `paths`.
-`bucket` may only be `procedure`, `personal`, or `wiki`; unknown values are routed to `wiki`.
+A run returns at most `max_units`; extraction merges cross-file evidence for the same abstraction and drops passing
+mentions, per-file summaries, and weak candidates without reusable value. `bucket` may only be `procedure`, `personal`,
+or `wiki`; unknown values are routed to `wiki`.
`topics` are proactive-interest candidates for the day. They contain `title`, `reason`, `evidence`, `keywords`, and
`paths` and are filtered again in the Topics stage.
-If there are no changed files, the flow ends early with success and skips later extraction work. If files changed but no LLM
-is configured, Extract fails because extraction requires an LLM.
+If there are no changed files, Extract succeeds with no units; Integrate then has no unit work, Topics preserves any
+existing target-day topics, and Finish still performs its normal catalog summary. If files changed but no LLM is
+configured, Extract fails because extraction requires an LLM.
### 2. Integrate
-`dream_integrate_step` invokes an agent independently for each unit and integrates that unit into one digest node. It exposes
-these tools to the agent:
+`dream_integrate_step` invokes an agent independently for each unit and integrates that unit into one digest node. It
+exposes these tools to the agent:
```text
node_search, read, frontmatter_read, write, edit, frontmatter_update
```
-This stage carries the core responsibility of `auto_link`. It first uses `node_search` to recall similar or related nodes at
-digest-node granularity, decides whether to create or update a node, and finally writes sources and related digest nodes as
-wikilinks. See [Auto Link](./auto_link.md) for the recall, deduplication, and edge-writing rules.
+This stage carries the core responsibility of `auto_link`. It first uses `node_search` to recall similar or related
+nodes at digest-node granularity, decides whether to create or update a node, and finally writes sources and related
+digest nodes as wikilinks. See [Auto Link](./auto_link.md) for the recall, deduplication, and edge-writing rules.
+
+Extract is the gate for deciding whether material is worth remembering, so Integrate has no `SKIP` action: each admitted
+unit must land in exactly one digest node. Creates and updates must retain provenance and weave related digest links
+into contextual sentences; bare wikilinks and standalone relationship fields are not valid output.
There are four integration actions:
-| Action | Meaning |
-|---|---|
-| `CREATE` | No equivalent abstraction exists; create a new digest node. |
+| Action | Meaning |
+|---------------|--------------------------------------------------------------------------------|
+| `CREATE` | No equivalent abstraction exists; create a new digest node. |
| `CORROBORATE` | The same memory appeared again; append a source or strengthen the description. |
-| `REFINE` | New material adds boundaries, steps, prerequisites, applicability, or detail. |
-| `CORRECT` | New material corrects errors, omissions, or conflicts in the existing node. |
+| `REFINE` | New material adds boundaries, steps, prerequisites, applicability, or detail. |
+| `CORRECT` | New material corrects errors, omissions, or conflicts in the existing node. |
-Successfully integrated units are recorded in `integrate_results`. Failed units enter `failed_units`, and their source paths
-enter `failed_paths`. The Finish stage does not checkpoint failed paths, ensuring that they can be retried later.
+Successfully integrated units are recorded in `integrate_results`. Failed units enter `failed_units`, and their source
+paths enter `failed_paths`. The Finish stage does not checkpoint failed paths, ensuring that they can be retried later.
### 3. Topics
@@ -127,7 +148,7 @@ It reads:
```text
daily//interests.yaml
-daily//interests.yaml
+daily//interests.yaml
```
Existing topics from the same day are preserved, while similar topics from the previous `topic_diversity_days` days are
@@ -156,7 +177,8 @@ topics:
`dream_finish_step` completes the run:
1. Write successfully processed changed paths to `file_catalog: dream`.
-2. Also write `daily//interests.yaml` and `daily/.md` to the catalog.
+2. Also write the target `daily//interests.yaml` and every refreshed day-index page in the scan window to the
+ catalog.
3. Persist the dream catalog if there were upserts or deletions.
4. Return a summary containing counts for scanned, changed, integrated, topics, checkpoints, and related values.
@@ -177,6 +199,12 @@ With caller guidance:
reme auto_dream date=2026-06-20 hint="Prioritize engineering decisions and long-term preferences"
```
+Override the default scan window and unit cap:
+
+```bash
+reme auto_dream date=2026-06-20 scan_days=3 max_units=8
+```
+
The same set of steps can also be placed in a `cron` Job, for example to run every morning:
```yaml
@@ -195,15 +223,16 @@ jobs:
## Important Boundaries
-`auto_dream` consumes only daily inputs and does not rewrite daily bodies. Daily preserves facts and the original situation;
-digest is the abstracted long-term memory layer.
+`auto_dream` consumes only daily inputs and does not rewrite daily bodies. Daily preserves facts and the original
+situation; digest is the abstracted long-term memory layer.
-`digest` is not a copy of the source text. Its body should preserve reusable abstractions, while a Sources section points
-back with entries such as `- [[daily//...]]`. Links follow the workspace-relative wikilink semantics described in
+`digest` is not a copy of the source text. Its body should preserve reusable abstractions, while a Sources section
+points back with contextual sentences such as `The decision was recorded in [[daily//decision.md]].` Links follow
+the workspace-relative wikilink semantics described in
[Memory as File](./memory_as_file.md).
-`auto_dream` does not invent an overview from nothing. Only content that actually appears in daily input and is extracted as
-a unit or topic can enter digest or `interests.yaml`.
+`auto_dream` does not invent an overview from nothing. Only content that actually appears in daily input and is
+extracted as a unit or topic can enter digest or `interests.yaml`.
-The complete flow depends on an LLM for Extract and Integrate. Topics can perform local deduplication without an LLM, but that
-does not mean the full dream flow can run offline.
+The complete flow depends on an LLM for Extract and Integrate. Topics can perform local deduplication without an LLM,
+but that does not mean the full dream flow can run offline.
diff --git a/docs/en/auto_link.md b/docs/en/auto_link.md
index 0a97976a..dc016e9e 100644
--- a/docs/en/auto_link.md
+++ b/docs/en/auto_link.md
@@ -1,11 +1,12 @@
# Auto Link
-In the current implementation, `auto_link` is not a separately registered Job. It is a capability of the Integrate stage in
+In the current implementation, `auto_link` is not a separately registered Job. It is a capability of the Integrate stage
+in
`auto_dream`: when `dream_integrate_step` writes a memory unit to `digest/`, it also recalls digest nodes, makes a
deduplication decision, links sources, and weaves wikilinks to related nodes into the result.
-For the complete dream flow, see [Auto Dream](./auto_dream.md). For general wikilink, frontmatter, and workspace-relative
-path semantics, see [Memory as File](./memory_as_file.md). For question-answering retrieval, see
+For the complete dream flow, see [Auto Dream](./auto_dream.md). For general wikilink, frontmatter, and
+workspace-relative path semantics, see [Memory as File](./memory_as_file.md). For question-answering retrieval, see
[Memory Search](./memory_search.md).
## Where It Runs
@@ -21,19 +22,19 @@ auto_dream:
- dream_finish_step
```
-The Integrate stage processes each unit independently. A unit is written to exactly one target digest node, but that node may
-link to multiple sources and multiple related digest nodes.
+The Integrate stage processes each unit independently. A unit is written to exactly one target digest node, but that
+node may link to multiple sources and multiple related digest nodes.
## Goals
`auto_link` addresses graph quality at write time:
-| Problem | Handling |
-|---|---|
-| The same memory already exists | Recall and update the existing node instead of creating a duplicate. |
-| New and existing material are related | Write workspace-relative wikilinks into the body. |
-| A digest node is disconnected from its sources | Add daily/resource links under a `## Sources` section. |
-| A node contains only isolated prose | Add links to related digest nodes on both CREATE and UPDATE. |
+| Problem | Handling |
+|------------------------------------------------|----------------------------------------------------------------------|
+| The same memory already exists | Recall and update the existing node instead of creating a duplicate. |
+| New and existing material are related | Write workspace-relative wikilinks into the body. |
+| A digest node is disconnected from its sources | Add daily/resource links under a `## Sources` section. |
+| A node contains only isolated prose | Add links to related digest nodes on both CREATE and UPDATE. |
## Toolchain
@@ -48,41 +49,42 @@ edit
frontmatter_update
```
-`node_search` is digest-only node retrieval designed for dream integration. It returns node-level signals such as the digest
-node's `path` and the `name` and `description` from frontmatter. It does not expand the body and does not perform the link
-expansion used by ordinary search.
+`node_search` is digest-only node retrieval designed for dream integration. It returns node-level signals such as the
+digest node's `path` and the `name` and `description` from frontmatter. It does not expand the body and does not perform
+the link expansion used by ordinary search.
-`read` and `frontmatter_read` are used only for candidates that may be relevant, avoiding expansion of every recalled result
-into a large context.
+`read` and `frontmatter_read` are used only for candidates that may be relevant, avoiding expansion of every recalled
+result into a large context.
## Linking Flow
### 1. Recall candidate nodes
-The agent first calls `node_search` with the unit's triggers, verbs, nouns, synonyms, and possible failure modes. Broad recall,
-for example `limit=20-30`, is recommended by default because this step serves both deduplication and link discovery.
+The agent first calls `node_search` with the unit's triggers, verbs, nouns, synonyms, and possible failure modes. Broad
+recall, for example `limit=20-30`, is recommended by default because this step serves both deduplication and link
+discovery.
Recalled results are internally classified into three groups:
-| Classification | Meaning | Next action |
-|---|---|---|
-| `same_abstraction` | The trigger or underlying abstraction is the same, with substantial content overlap. | Use as the UPDATE target. |
-| `related` | An adjacent process, prerequisite, failure mode, concept, preference, or upstream/downstream knowledge. | Write a body wikilink. |
-| `unrelated` | Only superficially similar or unrelated. | Ignore. |
+| Classification | Meaning | Next action |
+|--------------------|---------------------------------------------------------------------------------------------------------|---------------------------|
+| `same_abstraction` | The trigger or underlying abstraction is the same, with substantial content overlap. | Use as the UPDATE target. |
+| `related` | An adjacent process, prerequisite, failure mode, concept, preference, or upstream/downstream knowledge. | Write a body wikilink. |
+| `unrelated` | Only superficially similar or unrelated. | Ignore. |
### 2. Choose a write action
Every unit must select one action:
-| Action | Linking semantics |
-|---|---|
-| `CREATE` | Write a new `digest//.md` and add source and related-node links to its body. |
-| `CORROBORATE` | The same abstraction appeared again; append its source link and strengthen the description when needed. |
-| `REFINE` | New material extends the existing node; insert the additional content in the appropriate section and preserve existing links. |
-| `CORRECT` | New material corrects the existing node; use source links to identify the basis for the correction. |
+| Action | Linking semantics |
+|---------------|-------------------------------------------------------------------------------------------------------------------------------|
+| `CREATE` | Write a new `digest//.md` and add source and related-node links to its body. |
+| `CORROBORATE` | The same abstraction appeared again; append its source link and strengthen the description when needed. |
+| `REFINE` | New material extends the existing node; insert the additional content in the appropriate section and preserve existing links. |
+| `CORRECT` | New material corrects the existing node; use source links to identify the basis for the correction. |
-An UPDATE should be additive whenever possible: do not delete existing wikilinks or source entries. This prevents
-later graph indexing and retrieval from losing edges.
+An UPDATE should be additive whenever possible: do not delete existing wikilinks or source entries. This prevents later
+graph indexing and retrieval from losing edges.
### 3. Write source edges
@@ -91,12 +93,13 @@ Source edges are ordinary wikilinks grouped under a Markdown heading:
```markdown
## Sources
-- [[daily/2026-06-20/session.md]]
-- [[resource/2026-06-20/paper.md]]
+The decision was recorded in [[daily/2026-06-20/session.md]], while the supporting technical evidence comes from
+[[resource/2026-06-20/paper.md]].
```
-These edges represent the evidence behind a digest node. Plain-text descriptions do not count as source edges because only
-wikilinks can be parsed reliably by the file graph. For the complete parsing rules, see
+These edges represent the evidence behind a digest node. Plain-text descriptions do not count as source edges because
+only wikilinks can be parsed reliably by the file graph. The surrounding sentence must explain what each source
+supports; a bare wikilink line is not valid Integrate output. For the complete parsing rules, see
[Memory as File](./memory_as_file.md#wikilink).
### 4. Write relationships between digest nodes
@@ -113,11 +116,11 @@ This design extends [[digest/wiki/hybrid-search.md]] and uses
`auto_link` adjusts the shape of its output according to the unit bucket:
-| Bucket | Writing focus |
-|---|---|
-| `procedure` | Write a runbook with triggers, steps, inputs, and failure modes. Link prerequisites, substeps, and related preferences. |
-| `personal` | Write user-, team-, or project-specific facts and preferences. Link related projects, habits, and decision context. |
-| `wiki` | Write general knowledge, principles, observations, and decision precedents. Link concepts, methods, and adjacent knowledge. |
+| Bucket | Writing focus |
+|-------------|-----------------------------------------------------------------------------------------------------------------------------|
+| `procedure` | Write a runbook with triggers, steps, inputs, and failure modes. Link prerequisites, substeps, and related preferences. |
+| `personal` | Write user-, team-, or project-specific facts and preferences. Link related projects, habits, and decision context. |
+| `wiki` | Write general knowledge, principles, observations, and decision precedents. Link concepts, methods, and adjacent knowledge. |
Regardless of bucket, preserve source edges and weave recalled related digest nodes into the body whenever possible.
@@ -125,19 +128,19 @@ Regardless of bucket, preserve source edges and weave recalled related digest no
`auto_link` uses `node_search`, not the question-answering `search`.
-| Capability | Purpose |
-|---|---|
-| `search` | External question answering; returns chunks and can expand upstream/downstream link context. |
+| Capability | Purpose |
+|---------------|-----------------------------------------------------------------------------------------------------------|
+| `search` | External question answering; returns chunks and can expand upstream/downstream link context. |
| `node_search` | Dream integration; recalls only digest node-level summaries for deduplication and related-link decisions. |
-This boundary matters. The Integrate stage needs to decide whether the same abstraction already exists and which nodes should
-be linked; it should not load large numbers of body chunks into context. [Memory Search](./memory_search.md) handles
-question-oriented chunk retrieval, RRF fusion, and link expansion.
+This boundary matters. The Integrate stage needs to decide whether the same abstraction already exists and which nodes
+should be linked; it should not load large numbers of body chunks into context. [Memory Search](./memory_search.md)
+handles question-oriented chunk retrieval, RRF fusion, and link expansion.
## Failure and Retry
If integration of a unit fails, `dream_integrate_step` records `failed_units` and `failed_paths`.
`dream_finish_step` does not checkpoint those source paths, so the next `auto_dream` run processes them again.
-This makes auto_link writes retryable: a failure does not mark the input as complete or silently discard digest edges that
-should have been created.
+This makes auto_link writes retryable: a failure does not mark the input as complete or silently discard digest edges
+that should have been created.
diff --git a/docs/en/auto_memory.md b/docs/en/auto_memory.md
index c29c1e4a..ffe3db95 100644
--- a/docs/en/auto_memory.md
+++ b/docs/en/auto_memory.md
@@ -1,8 +1,9 @@
# Auto Memory
-Auto Memory is ReMe's entry point for conversational memory. Each conversation is first distilled into a daily memory card
-identified by `session_id`, and the day's `YYYY-MM-DD.md` page then indexes all of those cards. It turns "we talked about it"
-into "it was remembered" while preserving the original conversation as evidence.
+Auto Memory is ReMe's entry point for conversational memory. Within a target date, it uses `session_id` to find or update at
+most one daily memory card, whose filename is a concise topic or event name chosen by the Agent. The day's `YYYY-MM-DD.md`
+page indexes those cards. It turns "we talked about it" into "it was remembered" while retaining a source conversation record
+as evidence.
@@ -13,9 +14,9 @@ For the general file semantics of `daily/`, `session/`, frontmatter, and wikilin
```text
Conversation
- ├─ step 1: daily/YYYY-MM-DD/.md # one card per conversation
- ├─ step 2: daily/YYYY-MM-DD.md # daily index linking the cards
- └─ source: session/dialog/.jsonl # original conversation
+ ├─ step 1: daily/YYYY-MM-DD/.md # one topic-named card per session
+ ├─ step 2: daily/YYYY-MM-DD.md # daily index linking the cards
+ └─ source: session/dialog/.jsonl # source conversation record
```
## What It Records
@@ -39,29 +40,33 @@ workspace/
daily/
2026-06-20.md
2026-06-20/
- session-a.md
- session-b.md
+ login-refactor-decision.md
+ retrieval-regression.md
```
-`daily/2026-06-20/session-a.md` and `daily/2026-06-20/session-b.md` are memory cards distilled from different
-conversations. `daily/2026-06-20.md` is the index page for that day. Resource files enter the same daily memory layer; see
+The two files under the date directory are topic-named cards distilled from different conversations.
+`daily/2026-06-20.md` is the index page for that day. Resource files enter the same daily memory layer; see
[Auto Resource](./auto_resource.md).
-When a call includes `session_id`, Auto Memory records that conversation separately under the given ID:
+When a call includes `session_id`, Auto Memory uses it to find the corresponding card through frontmatter, while the Agent
+chooses a readable filename through `name`:
-```text
-daily/2026-06-20/session-a.md
+```yaml
+name: login-refactor-decision
+session_id: session-a
+source_conversation: "[[session/dialog/session-a.jsonl]]"
```
-This keeps different conversations separate. A requirements discussion, a debugging session, and a documentation update can
-each have their own memory card. To see what happened on a particular day, start with `YYYY-MM-DD.md`. To inspect what was
-distilled from one conversation, open the corresponding `.md`.
+This keeps different conversations separate without forcing opaque IDs into filenames. An update locates the existing note by
+`session_id` or `source_conversation`; if the Agent supplies a better frontmatter `name`, the system can rename the note and
+retarget inbound wikilinks. To see what happened on a day, start with `YYYY-MM-DD.md`.
## Preserving the Original Information
-The distilled daily note is optimized for readability; the original conversation is retained for trust and verification.
+The distilled daily note is optimized for readability; a filtered source conversation record is retained for trust and
+verification.
-While generating memory cards, Auto Memory also saves the raw sessions:
+While generating memory cards, Auto Memory also saves the source messages:
```text
session/
@@ -70,12 +75,12 @@ session/
session-b.jsonl
```
-Each daily note points to its corresponding original conversation. When a memory needs verification, follow that link back to
-the complete context in which it was created.
+Each daily note points to its corresponding conversation record. Saved messages omit tool-result blocks and base64 data
+blocks, preventing recalled memory and binary payloads from being mistaken for user-provided evidence later.
## Message Timestamps
-Auto Memory preserves each message's `created_at` in both the prompt and the raw session JSONL. When importing historical
+Auto Memory preserves each retained message's `created_at` in both the prompt and the source conversation JSONL. When importing historical
conversations or benchmark data, provide the actual occurrence time for every message so the model does not confuse event
time with execution time:
@@ -92,8 +97,8 @@ For compatibility with common dataset schemas, `auto_memory` also checks `time_c
`timeCreated`, and `created_time` when `created_at` is absent. These fields may appear either at the top level of a message
or inside `metadata`.
-When a call does not explicitly provide `date`, Auto Memory uses the date of the earliest valid `created_at` value in the
-messages. If no message contains a valid timestamp, it falls back to the current date. Historical imports may also specify the
+When a call does not explicitly provide `date`, Auto Memory uses the latest valid `created_at` date in the messages. If no
+message contains a valid timestamp, it falls back to the current date. Historical imports may also specify the
target date directly:
```bash
diff --git a/docs/en/auto_resource.md b/docs/en/auto_resource.md
index a3ae3f19..9d9495b1 100644
--- a/docs/en/auto_resource.md
+++ b/docs/en/auto_resource.md
@@ -1,8 +1,8 @@
# Auto Resource `Beta`
Auto Resource is ReMe's entry point for interpreting resources and is currently in **Beta**. Resource files first enter
-`resource/` by date and are then interpreted into daily resource cards. Each card's filename comes from the LLM-generated
-frontmatter `name`, and `source_resource` links the card back to its original file.
+`resource/`, preferably under a date directory, and are then interpreted into daily resource cards. Each card's filename
+comes from the LLM-generated frontmatter `name`, and `source_resource` links the card back to its original file.
@@ -13,7 +13,7 @@ For the general file semantics of workspace layers, `resource/`, and `daily/`, s
[Auto Memory](./auto_memory.md).
```text
-resource/YYYY-MM-DD/
+resource/[YYYY-MM-DD/]
├─ step 1: daily/YYYY-MM-DD/.md # interpreted resource card
├─ step 2: source_resource points to the original resource
└─ step 3: daily/YYYY-MM-DD.md # daily index linking the cards
@@ -21,8 +21,8 @@ resource/YYYY-MM-DD/
## What It Records
-Auto Resource does more than copy file content. It extracts information that will make the resource easier to retrieve and
-understand later:
+Auto Resource does more than copy file content. It extracts information that will make the resource easier to retrieve
+and understand later:
- Core content: what the resource is mainly about.
- Structure: its sections, tables, fields, and data organization.
@@ -34,26 +34,28 @@ In short, it turns "a file was archived" into "the resource is usable."
## Original Resource Entry Point
-Auto Resource uses `resource/` as the entry point for source material. Resources must be placed under a date, which determines
-the day whose daily memory layer receives the interpreted card.
+Auto Resource uses `resource/` as the entry point for source material. Date directories are recommended, and their date
+determines which daily memory layer receives the interpreted card. A file directly under `resource/` is also supported
+and uses today in the application timezone.
Example directory:
```text
workspace/
resource/
+ quick-note.txt # enters today's daily layer
2026-06-20/
market-report.md
meeting-notes.csv
```
-The current Beta version is best suited to text-based resources such as `md`, `txt`, `json`, `jsonl`, `csv`, `yaml`,
-and `html`.
+The current Beta version is best suited to text-based resources such as `md`, `txt`, `json`, `jsonl`, `csv`, `yaml`, and
+`html`.
## Resource Cards
-Each resource file produces one daily resource card. The system initially uses the resource file's stem as a temporary path.
-After the agent writes the card, the file is renamed according to its frontmatter `name`:
+Each resource file produces one daily resource card. The system initially uses the resource file's stem as a temporary
+path. After the agent writes the card, the file is renamed according to its frontmatter `name`:
```text
resource/2026-06-20/market-report.md
@@ -67,14 +69,14 @@ The resource card links to the original file through frontmatter:
source_resource: "[[resource/2026-06-20/market-report.md]]"
```
-When a resource changes, Auto Resource finds and updates the corresponding card through `source_resource`. When a resource is
-deleted, its daily note is also removed. The older `daily/YYYY-MM-DD/.md` naming convention remains supported
-as a fallback.
+When a resource changes, Auto Resource finds and updates the corresponding card through `source_resource`. When a
+resource is deleted, its daily note is also removed. The older `daily/YYYY-MM-DD/.md` naming convention
+remains supported as a fallback.
## Daily Index
-Resource cards enter the same daily memory layer as Auto Memory cards. The day's `YYYY-MM-DD.md` page acts as an index and
-organizes those resource cards:
+Resource cards enter the same daily memory layer as Auto Memory cards. The day's `YYYY-MM-DD.md` page acts as an index
+and organizes those resource cards:
```text
daily/
@@ -91,11 +93,13 @@ resource, open its corresponding resource card.
The interpreted daily note is optimized for readability; the original resource is retained for trust and verification.
-Auto Resource does not move the original file. It remains under `resource/YYYY-MM-DD/`. Text resources can therefore enter
-the daily memory flow while their source files stay in their original location.
+Auto Resource does not move the original file. It remains at its original path under `resource/`. Text resources can
+therefore enter the daily memory flow while their source files stay in their original location.
## What Happens Next
-Auto Resource only creates resource interpretations in the daily layer. To distill long-term knowledge from resources into
-`digest/`, use [Auto Dream](./auto_dream.md). To search original resources, daily cards, and digest nodes, use
-[Memory Search](./memory_search.md).
+Auto Resource only creates resource interpretations in the daily layer. To distill long-term knowledge from resources
+into
+`digest/`, use [Auto Dream](./auto_dream.md). The default live index covers daily cards and digest nodes. Run
+`reme reindex`
+when original resource files must also be directly searchable; see [Memory Search](./memory_search.md).
diff --git a/docs/en/contributing.md b/docs/en/contributing.md
index b4fea323..571af317 100644
--- a/docs/en/contributing.md
+++ b/docs/en/contributing.md
@@ -8,12 +8,12 @@ ReMe is open source and hosted on GitHub:
## How to Contribute
-Thank you for your interest in ReMe. ReMe is a file-first, self-evolving memory system for agents. Contributions are welcome
-through issue reports, documentation improvements, additional tests, bug fixes, and new capabilities.
+Thank you for your interest in ReMe. ReMe is a file-first, self-evolving memory system for agents. Contributions are
+welcome through issue reports, documentation improvements, additional tests, bug fixes, and new capabilities.
-If this is your first time running ReMe locally, start with [Quick Start](./quick_start.md). If your change affects runtime
-layers, Jobs, Steps, or components, read [ReMe Framework](./framework.md). If it affects workspace directories, frontmatter,
-wikilinks, or chunking, read [Memory as File](./memory_as_file.md).
+If this is your first time running ReMe locally, start with [Quick Start](./quick_start.md). If your change affects
+runtime layers, Jobs, Steps, or components, read [ReMe Framework](./framework.md). If it affects workspace directories,
+frontmatter, wikilinks, or chunking, read [Memory as File](./memory_as_file.md).
### 1. Before You Begin
@@ -21,9 +21,10 @@ Before investing in an implementation:
- Check [Open Issues](https://github.com/agentscope-ai/ReMe/issues) for an existing issue or discussion.
- If a related issue is still open, comment that you would like to work on it to avoid duplicate effort.
-- If no issue exists, create one describing the context, expected behavior, possible implementation, and scope of impact.
-- For larger feature changes, align with maintainers on interfaces, configuration, compatibility, and test strategy before
- submitting an implementation.
+- If no issue exists, create one describing the context, expected behavior, possible implementation, and scope of
+ impact.
+- For larger feature changes, align with maintainers on interfaces, configuration, compatibility, and test strategy
+ before submitting an implementation.
### 2. Local Development Environment
@@ -53,8 +54,8 @@ CLI / Client -> Service -> Application -> Job -> Step -> Component / Workspace
In practice:
-- Capabilities exposed to users or external systems should normally be orchestrated by a Job, then exposed by a Service as a
- CLI-, HTTP-, or MCP-callable interface.
+- Capabilities exposed to users or external systems should normally be orchestrated by a Job, then exposed by a Service
+ as a CLI-, HTTP-, or MCP-callable interface.
- Reusable infrastructure belongs in `reme/components/`, with dependencies declared through `BaseComponent.bind()`.
- Atomic business operations belong in `reme/steps/` and access the file store, agent wrapper, catalog, LLM, and other
components through `BaseStep.Ref`.
@@ -65,31 +66,33 @@ In practice:
When adding a Step or Job, pay particular attention to these conventions:
-- Register implementations with `@R.register("")`. Registration names should be stable, clear, and match the
- configured `backend`.
-- After adding a Step file, make sure its package `__init__.py` imports the module; otherwise, the registry will not load it.
+- Register implementations with `@R.register("")`. Registration names should be stable, clear, and match
+ the configured `backend`.
+- After adding a Step file, make sure its package `__init__.py` imports the module; otherwise, the registry will not
+ load it.
- A Step should perform one atomic business operation. Cross-step flows belong in Job configuration or a dedicated
orchestration Step.
-- A Job composes Steps and selects normal, streaming, background, or scheduled execution. `enable_serve` controls whether it
- is externally exposed.
+- A Job composes Steps and selects normal, streaming, background, or scheduled execution. `enable_serve` controls
+ whether it is externally exposed.
- When a Step needs components, prefer `BaseStep.Ref`. Do not reconstruct global components inside a Step or bypass
`ApplicationContext`.
- File, index, graph, frontmatter, and wikilink behavior must preserve consistent workspace-relative path semantics.
-- Add fast tests under `tests/unit/` for new capabilities. Put cross-component, LLM, embedding, or service behavior under
+- Add fast tests under `tests/unit/` for new capabilities. Put cross-component, LLM, embedding, or service behavior
+ under
`tests/integration/` when appropriate.
### 4. Code and Documentation Changes
Choose the appropriate entry point for the type of change:
-| Change type | Primary location | Guidance |
-|---|---|---|
-| Configuration or startup behavior | `reme/config/`, `reme/application.py`, `reme/reme.py` | Keep the default configuration runnable and avoid breaking existing CLI, HTTP, and MCP entry points. |
-| Component capability | `reme/components/` | Reuse `BaseComponent`, the registry, and context objects. |
-| Job or Step | `reme/components/job/`, `reme/steps/` | Follow the Job -> Step model in [ReMe Framework](./framework.md), keep request and response schemas clear, and add corresponding tests. |
-| Data structure | `reme/schema/`, `reme/enumeration/` | Preserve serialization compatibility and existing frontmatter and wikilink semantics. |
-| Utility | `reme/utils/` | Keep function boundaries small and cover edge cases with unit tests. |
-| User documentation | `docs/en/`, `README.md` | Update documentation when user-visible behavior changes. |
+| Change type | Primary location | Guidance |
+|-----------------------------------|-------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------|
+| Configuration or startup behavior | `reme/config/`, `reme/application.py`, `reme/reme.py` | Keep the default configuration runnable and avoid breaking existing CLI, HTTP, and MCP entry points. |
+| Component capability | `reme/components/` | Reuse `BaseComponent`, the registry, and context objects. |
+| Job or Step | `reme/components/job/`, `reme/steps/` | Follow the Job -> Step model in [ReMe Framework](./framework.md), keep request and response schemas clear, and add corresponding tests. |
+| Data structure | `reme/schema/`, `reme/enumeration/` | Preserve serialization compatibility and existing frontmatter and wikilink semantics. |
+| Utility | `reme/utils/` | Keep function boundaries small and cover edge cases with unit tests. |
+| User documentation | `docs/en/`, `README.md` | Update documentation when user-visible behavior changes. |
If a change involves an LLM, embeddings, an external service, file watching, or a background task, also describe its
dependencies, failure behavior, and local validation method.
@@ -165,15 +168,16 @@ pytest tests/unit/test_reme_cli.py
If `pre-commit` modifies files automatically, commit those changes and rerun the checks until everything passes.
-The current pre-commit configuration includes YAML/TOML/JSON validation, private-key detection, trailing-whitespace checks,
+The current pre-commit configuration includes YAML/TOML/JSON validation, private-key detection, trailing-whitespace
+checks,
`black`, `flake8`, `pylint`, and `pyroma`. The main formatting rules are:
- `black --line-length=120`
- `flake8 --max-line-length=120`
- `pylint --max-line-length=120`
-Some integration tests may require an LLM, embeddings, or external service configuration. If you cannot run them locally,
-state why they were skipped and what alternative validation you completed in the PR description.
+Some integration tests may require an LLM, embeddings, or external service configuration. If you cannot run them
+locally, state why they were skipped and what alternative validation you completed in the PR description.
### 8. Testing Requirements
@@ -183,7 +187,8 @@ Add tests according to the risk of the change:
- For a new Step, Job, or component, cover at least the main path and a failure path.
- For changes to shared logic such as indexes, graphs, wikilinks, frontmatter, or file operations, add edge cases.
- For changes to the CLI, services, or configuration parsing, cover the user-visible entry point.
-- Documentation-only changes usually do not require new tests, but running `pre-commit run --all-files` is still recommended.
+- Documentation-only changes usually do not require new tests, but running `pre-commit run --all-files` is still
+ recommended.
Place tests according to the existing structure:
@@ -213,9 +218,9 @@ Documentation should:
- Bugs and feature requests: [GitHub Issues](https://github.com/agentscope-ai/ReMe/issues)
- Project home: [GitHub Repository](https://github.com/agentscope-ai/ReMe)
-- Documentation site: [https://reme.agentscope.io/](https://reme.agentscope.io/)
+- Documentation site: [https://docs.agentscope.io/reme](https://docs.agentscope.io/reme)
---
-Thank you for contributing to ReMe. Your improvements help make long-term memory for agents more readable, controllable, and
-maintainable.
+Thank you for contributing to ReMe. Your improvements help make long-term memory for agents more readable, controllable,
+and maintainable.
diff --git a/docs/en/framework.md b/docs/en/framework.md
index ec3836c1..5774e734 100644
--- a/docs/en/framework.md
+++ b/docs/en/framework.md
@@ -16,13 +16,13 @@ To run and use ReMe first, see [Quick Start](./quick_start.md). For workspace fi
### Capability Boundary
-ReMe v4 focuses on long-term memory: it distills conversations and resources into `daily/`, organizes them into `digest/`,
-and exposes write, retrieval, and proactive-read capabilities through the CLI, HTTP, and MCP.
+ReMe v4 focuses on long-term memory: it distills conversations and resources into `daily/`, organizes them into
+`digest/`, and exposes write, retrieval, and proactive-read capabilities through the CLI, HTTP, and MCP.
-Single-session context-window management is outside the scope of ReMe v4. This includes compressing the current conversation,
-injecting summaries, trimming tool output, or providing an independent `/compact` interface. Those capabilities belong in
-the host agent framework. ReMe accepts conversations, resources, and file changes that have already occurred and persists the
-information with long-term value.
+Single-session context-window management is outside the scope of ReMe v4. This includes compressing the current
+conversation, injecting summaries, trimming tool output, or providing an independent `/compact` interface. Those
+capabilities belong in the host agent framework. ReMe accepts conversations, resources, and file changes that have
+already occurred and persists the information with long-term value.
```mermaid
flowchart LR
@@ -38,16 +38,16 @@ flowchart LR
Core layers:
-| Layer | Main location | Responsibility |
-|---|---|---|
-| CLI | `reme/reme.py` | Parse commands; `start` launches the service; other actions call the service through a client. |
-| Service | `reme/components/service/` | Register Jobs as HTTP endpoints or MCP tools. |
-| Application | `reme/application.py` | Assemble configured objects, start them in dependency order, close them, and invoke Jobs. |
-| Job | `reme/components/job/` | Orchestrate Steps and select normal, streaming, background, or scheduled execution. |
-| Step | `reme/steps/` | Atomic business operations such as file I/O, retrieval, indexing, and self-evolution. |
-| Component | `reme/components/` | Reusable infrastructure such as file_store, file_graph, keyword_index, and agent_wrapper. |
-| Schema | `reme/schema/` | Data structures such as `Request`, `Response`, `FileChunk`, `FileNode`, and configuration models. |
-| Config | `reme/config/` | Default YAML configuration and command-line override parsing. |
+| Layer | Main location | Responsibility |
+|-------------|----------------------------|---------------------------------------------------------------------------------------------------|
+| CLI | `reme/reme.py` | Parse commands; `start` launches the service; other actions call the service through a client. |
+| Service | `reme/components/service/` | Register Jobs as HTTP endpoints or MCP tools. |
+| Application | `reme/application.py` | Assemble configured objects, start them in dependency order, close them, and invoke Jobs. |
+| Job | `reme/components/job/` | Orchestrate Steps and select normal, streaming, background, or scheduled execution. |
+| Step | `reme/steps/` | Atomic business operations such as file I/O, retrieval, indexing, and self-evolution. |
+| Component | `reme/components/` | Reusable infrastructure such as file_store, file_graph, keyword_index, and agent_wrapper. |
+| Schema | `reme/schema/` | Data structures such as `Request`, `Response`, `FileChunk`, `FileNode`, and configuration models. |
+| Config | `reme/config/` | Default YAML configuration and command-line override parsing. |
## 2. Directory Structure
@@ -68,18 +68,19 @@ reme/
file_store/ # file-index coordination layer
file_graph/ # wikilink graph
keyword_index/ # BM25 and other keyword indexes
- file_chunker/ # Markdown / default text chunking
+ file_chunker/ # Markdown / JSON / JSONL / generic text chunking
file_catalog/ # change checkpoints
as_llm/, as_embedding/ # model wrappers
- agent_wrapper/ # AgentScope / Claude Code wrappers
+ agent_wrapper/ # AgentScope / Claude Code / Codex wrappers
steps/
base_step.py # BaseStep, Ref, dispatch_steps
- common/ # version, help, health_check, demo
+ common/ # version, help, health_check, status, chat
+ benchmark/ # LongMemEval / BEAM evaluation steps
+ cookbook/ # optional research workflow steps
file_io/ # read/write/edit/delete/move/frontmatter/daily
index/ # watch/init/update/search/traverse
evolve/ # auto_memory, auto_resource, auto_dream, proactive
- transfer/ # upload/download/ingest
- channel/ # MCP channel tools
+ transfer/ # upload/download
```
The default workspace directories are defined by `ApplicationConfig`:
@@ -87,7 +88,8 @@ The default workspace directories are defined by `ApplicationConfig`:
```text
/
metadata/ # persistent file_store, file_graph, keyword_index, file_catalog, and related state
- session/ # agent sessions and original conversations
+ session/ # source conversations used by memory workflows
+ mem_session/ # generated Agent wrapper sessions and configuration
resource/ # external resources
daily/ # lightly processed memory
digest/ # long-term digest memory
@@ -127,13 +129,13 @@ reme search query="memory" backend=mcp
Configuration parsing supports:
-| Capability | Source | Description |
-|---|---|---|
-| Default configuration | `resolve_app_config()` | Load `reme/config/default.yaml` when `config` is not specified. |
-| Explicit configuration | `config=` | Accept a built-in configuration name or a YAML/JSON file path. |
-| Dot notation | `parse_dot_notation()` | For example, `service.port=8181`. |
-| Environment variables | `_expand_env_vars()` | Support `${VAR}` and `${VAR:-default}`. |
-| Value conversion | `_convert_value()` | Convert bool, int, float, JSON list/dict, and null values automatically. |
+| Capability | Source | Description |
+|------------------------|-------------------------|--------------------------------------------------------------------------|
+| Default configuration | `resolve_app_config()` | Load `reme/config/default.yaml` when `config` is not specified. |
+| Explicit configuration | `config=` | Accept a built-in configuration name or a YAML/JSON file path. |
+| Dot notation | `parse_dot_notation()` | For example, `service.port=8181`. |
+| Environment variables | `_expand_env_vars()` | Support `${VAR}` and `${VAR:-default}`. |
+| Value conversion | `_convert_value()` | Convert bool, int, float, JSON list/dict, and null values automatically. |
### 3.2 Service
@@ -157,22 +159,28 @@ flowchart LR
HTTP service behavior:
-| Job type | HTTP exposure |
-|---|---|
-| Non-`StreamJob` with `enable_serve: true` | `POST /` returning `Response` JSON. |
-| `StreamJob` | `POST /` returning `text/event-stream`. |
-| `enable_serve: false` | No endpoint is registered. |
+| Job type | HTTP exposure |
+|-------------------------------------------|---------------------------------------------------|
+| Non-`StreamJob` with `enable_serve: true` | `POST /` returning `Response` JSON. |
+| `StreamJob` | `POST /` returning `text/event-stream`. |
+| `enable_serve: false` | No endpoint is registered. |
+
+After registering Job endpoints, the HTTP service can also mount the ReMe Studio single-page application. The default is
+`service.web_enabled=true`. Builds are resolved from `service.web_static_dir`, `REME_WEB_STATIC_DIR`, packaged
+`reme/web`, and source-tree locations such as `website/dist-static`. If no `index.html` is found, only the frontend is
+skipped and the Job API remains available. The Studio `GET` fallback does not replace existing `POST /`
+routes.
MCP service behavior:
-| Job type | MCP exposure |
-|---|---|
-| Non-`StreamJob` with `enable_serve: true` | Registered as an MCP tool. |
-| `StreamJob` | Currently skipped and not registered. |
-| `BackgroundJob` | Forces `enable_serve=False` at construction and is never exposed. |
+| Job type | MCP exposure |
+|-------------------------------------------|-------------------------------------------------------------------|
+| Non-`StreamJob` with `enable_serve: true` | Registered as an MCP tool. |
+| `StreamJob` | Currently skipped and not registered. |
+| `BackgroundJob` | Forces `enable_serve=False` at construction and is never exposed. |
-MCP services can inject server-owned arguments with `injected_job_kwargs`; callers cannot override those arguments.
-Set `tool_error_on_failure: true` to expose an unsuccessful ReMe `Response` as an MCP tool error.
+MCP services can inject server-owned arguments with `injected_job_kwargs`; callers cannot override those arguments. Set
+`tool_error_on_failure: true` to expose an unsuccessful ReMe `Response` as an MCP tool error.
## 4. Registry and Dependency Injection
@@ -198,24 +206,24 @@ The registry key is:
`component_type` comes from a class attribute:
-| Type | Class attribute |
-|---|---|
-| Step | `BaseStep.component_type = ComponentEnum.STEP` |
-| Job | `BaseJob.component_type = ComponentEnum.JOB` |
-| Service | `BaseService.component_type = ComponentEnum.SERVICE` |
+| Type | Class attribute |
+|-----------|-----------------------------------------------------------|
+| Step | `BaseStep.component_type = ComponentEnum.STEP` |
+| Job | `BaseJob.component_type = ComponentEnum.JOB` |
+| Service | `BaseService.component_type = ComponentEnum.SERVICE` |
| FileStore | `BaseFileStore.component_type = ComponentEnum.FILE_STORE` |
-The same backend name can therefore exist under different component types. For example, `http` can be both a service backend
-and a client backend.
+The same backend name can therefore exist under different component types. For example, `http` can be both a service
+backend and a client backend.
### 4.2 Registration Through Module Imports
Registration happens when a module is imported. `reme/components/__init__.py` imports component packages, while
-`reme/steps/__init__.py` imports `channel/common/evolve/file_io/index/transfer`. Each package's `__init__.py` then imports
-its concrete modules, causing `@R.register(...)` to execute.
+`reme/steps/__init__.py` imports `benchmark/common/cookbook/evolve/file_io/index/transfer`. Each package's `__init__.py`
+then imports its concrete modules, causing `@R.register(...)` to execute.
-After adding a Step file, make sure the package's `__init__.py` imports it. Otherwise, the backend will not appear in the
-registry.
+After adding a Step file, make sure the package's `__init__.py` imports it. Otherwise, the backend will not appear in
+the registry.
### 4.3 Component.bind
@@ -234,18 +242,18 @@ flowchart LR
Rules for `BaseComponent.bind(name, BaseClass, optional=True)`:
-| Scenario | Behavior |
-|---|---|
-| `name` is empty | Return `None` and skip the dependency. |
-| `app_context` exists | Look up `app_context.components[ctype][name]`. |
-| Dependency missing and `optional=True` | Resolve to `None`. |
-| Dependency missing and `optional=False` | Fail at startup. |
-| Standalone mode | A private component can be created with `default_factory`. |
+| Scenario | Behavior |
+|-----------------------------------------|------------------------------------------------------------|
+| `name` is empty | Return `None` and skip the dependency. |
+| `app_context` exists | Look up `app_context.components[ctype][name]`. |
+| Dependency missing and `optional=True` | Resolve to `None`. |
+| Dependency missing and `optional=False` | Fail at startup. |
+| Standalone mode | A private component can be created with `default_factory`. |
### 4.4 Step.Ref
-Steps do not participate in component topological startup. They are created temporarily for each Job invocation. Steps access
-components primarily through `BaseStep.Ref`:
+Steps do not participate in component topological startup. They are created temporarily for each Job invocation. Steps
+access components primarily through `BaseStep.Ref`:
```python
file_store: BaseFileStore = Ref(BaseFileStore, ComponentEnum.FILE_STORE)
@@ -301,11 +309,13 @@ flowchart LR
F --> G["start CronJob"]
```
-During shutdown, objects in `_started_components` are closed in reverse order so dependents close before their dependencies.
+During shutdown, objects in `_started_components` are closed in reverse order so dependents close before their
+dependencies.
## 6. Job Model
-A Job is the orchestration unit for an externally callable capability or background task. Jobs are configured under `jobs:`
+A Job is the orchestration unit for an externally callable capability or background task. Jobs are configured under
+`jobs:`
in `reme/config/default.yaml`.
### 6.1 BaseJob
@@ -326,23 +336,23 @@ flowchart LR
Important source behavior:
-| Source | Behavior |
-|---|---|
-| `_start()` | Parse each Step config from YAML into `(step_cls, params)`. |
-| `_build_steps()` | Create new Step instances for every call, avoiding state shared across requests. |
-| `__call__()` | Create a `RuntimeContext` and execute Steps sequentially. |
-| Exception handling | Catch the exception, set `response.success=False`, and set `answer=str(e)`. |
+| Source | Behavior |
+|--------------------|----------------------------------------------------------------------------------|
+| `_start()` | Parse each Step config from YAML into `(step_cls, params)`. |
+| `_build_steps()` | Create new Step instances for every call, avoiding state shared across requests. |
+| `__call__()` | Create a `RuntimeContext` and execute Steps sequentially. |
+| Exception handling | Catch the exception, set `response.success=False`, and set `answer=str(e)`. |
### 6.2 StreamJob
`StreamJob` extends `BaseJob` but returns streaming chunks:
-| Behavior | Description |
-|---|---|
-| Context | Includes `stream_queue`. |
+| Behavior | Description |
+|-------------|------------------------------------------------------------|
+| Context | Includes `stream_queue`. |
| Step output | Call `context.add_stream_string(text, ChunkEnum.CONTENT)`. |
-| Exception | Write `ChunkEnum.ERROR`. |
-| Completion | Always send a `DONE` chunk. |
+| Exception | Write `ChunkEnum.ERROR`. |
+| Completion | Always send a `DONE` chunk. |
### 6.3 BackgroundJob
@@ -362,8 +372,8 @@ flowchart LR
J --> K["wait close_timeout; cancel on timeout"]
```
-The default `BackgroundJob.__call__()` also executes configured Steps in sequence, but it does not swallow exceptions, which
-allows the supervisor to restart the task.
+The default `BackgroundJob.__call__()` also executes configured Steps in sequence, but it does not swallow exceptions,
+which allows the supervisor to restart the task.
### 6.4 CronJob
@@ -389,7 +399,9 @@ The current implementation uses `croniter` to calculate the next trigger time. T
```mermaid
flowchart LR
Jobs["default.yaml jobs"] --> BG["background index_update_loop resource_watch_loop digest_watch_loop"]
- Jobs --> Base["base version / help / health_check search / node_search / traverse / reindex read / write / edit / delete / move / list / stat daily_list / daily_reindex / daily_write auto_memory / auto_resource / auto_dream / proactive"]
+ Jobs --> Cron["cron dream_cron optimize_index_cron"]
+ Jobs --> Stream["stream chat"]
+ Jobs --> Base["base version / help / health_check / status / app_config search / node_search / traverse / graph_snapshot / reindex read / load / read_image / write / save / edit / delete / move / list / stat / frontmatter_* daily_list / daily_reindex / daily_write auto_memory / auto_memory_cc / auto_resource / auto_dream / proactive"]
```
## 7. Step Model
@@ -413,12 +425,12 @@ flowchart LR
`RuntimeContext` is shared by all Steps within one Job invocation:
-| Field | Description |
-|---|---|
-| `response` | Final `Response(answer, success, metadata)`. |
-| `data` | Free-form dictionary containing input parameters and intermediate results. |
-| `stream_queue` | Output queue for streaming Jobs. |
-| `stop_event` | Stop signal for background Jobs. |
+| Field | Description |
+|----------------|----------------------------------------------------------------------------|
+| `response` | Final `Response(answer, success, metadata)`. |
+| `data` | Free-form dictionary containing input parameters and intermediate results. |
+| `stream_queue` | Output queue for streaming Jobs. |
+| `stop_event` | Stop signal for background Jobs. |
Common Step code:
@@ -482,21 +494,22 @@ flowchart LR
Current default components in `reme/config/default.yaml`:
-| ComponentEnum | Name | Backend | Description |
-|---|---|---|---|
-| `service` | singleton | `http` | Default HTTP service. |
-| `tokenizer` | `default` | `regex` | BM25 tokenizer. |
-| `as_embedding` | `default` | `${EMBEDDING_BACKEND:-openai}` | Embedding model wrapper. |
-| `embedding_store` | `default` | `local` | Embedding store depending on `as_embedding: default`. |
-| `as_llm` | `default` | `${LLM_BACKEND:-openai}` | LLM model wrapper. |
-| `agent_wrapper` | `default` | `agentscope` | AgentScope wrapper. |
-| `agent_wrapper` | `claude_code` | `claude_code` | Claude Code wrapper. |
-| `file_graph` | `default` | `local` | Wikilink graph. |
-| `file_catalog` | `default/resource/digest/dream` | `local` | File-change checkpoints. |
-| `file_chunker` | `markdown` | `markdown` | Markdown AST chunking. |
-| `file_chunker` | `default` | `default` | Default text chunking, currently supporting `jsonl`. |
-| `keyword_index` | `default` | `bm25` | BM25 keyword index. |
-| `file_store` | `default` | `local` | Combines file_graph and keyword_index; defaults to `embedding_store: ""`. |
+| ComponentEnum | Name | Backend | Description |
+|-------------------|---------------------------------|--------------------------------------------------|--------------------------------------------------------------------------------|
+| `service` | singleton | `http` | Default HTTP service. |
+| `tokenizer` | `default` | `regex` | BM25 tokenizer. |
+| `as_embedding` | `default` | Not configured by default; example uses `openai` | Provides the embedding model wrapper after uncommenting the example config. |
+| `embedding_store` | `default` | Not configured by default; example uses `local` | Depends on `as_embedding: default` after uncommenting the example config. |
+| `as_llm` | `default` | `${LLM_BACKEND:-openai}` | LLM model wrapper. |
+| `agent_wrapper` | `default` | `agentscope` | AgentScope wrapper. |
+| `agent_wrapper` | `claude_code` | `claude_code` | Claude Code wrapper. |
+| `agent_wrapper` | `codex/codex_oauth` | `codex` | Codex wrappers for API-key and OAuth authentication. |
+| `file_graph` | `default` | `local` | Wikilink graph. |
+| `file_catalog` | `default/resource/digest/dream` | `local` | File-change checkpoints. |
+| `file_chunker` | `markdown` | `markdown` | Markdown AST chunking. |
+| `file_chunker` | `json/jsonl/default` | `json/jsonl/default` | JSON, JSONL, and generic text chunkers; generic text supports `txt` and `log`. |
+| `keyword_index` | `default` | `bm25` | BM25 keyword index. |
+| `file_store` | `default` | `local` | Combines file_graph and keyword_index; defaults to `embedding_store: ""`. |
Note that the `search` Step configuration contains `vector_weight`, but `file_store.default.embedding_store` is empty by
default. Vector retrieval is available only when the runtime configuration enables an embedding store.
@@ -554,12 +567,12 @@ class MySearchStep(BaseStep):
Common attributes available directly:
-| Attribute | Component resolved by default |
-|---|---|
-| `self.as_llm` | `.model` from `as_llm: default`. |
+| Attribute | Component resolved by default |
+|----------------------|-------------------------------------|
+| `self.as_llm` | `.model` from `as_llm: default`. |
| `self.agent_wrapper` | `agent_wrapper: default`; optional. |
-| `self.file_catalog` | `file_catalog: default`; optional. |
-| `self.file_store` | `file_store: default`. |
+| `self.file_catalog` | `file_catalog: default`; optional. |
+| `self.file_store` | `file_store: default`. |
To select a non-default component from Job configuration:
@@ -571,13 +584,13 @@ steps:
### 9.4 Step Design Guidance
-| Guidance | Reason |
-|---|---|
-| Read input from `context` and write intermediate results to `context`. | A multi-Step Job passes data through the same context. |
-| Write the final result to `context.response`. | Services and clients consume the standard `Response`. |
-| Do not store request-scoped state on a Step instance. | A Step is rebuilt for every Job call, and stateless Steps are easier to test. |
-| A background loop that supports interruption should check `context.stop_event`. | `BackgroundJob.close()` relies on the stop event for graceful shutdown. |
-| Call `add_stream_string()` only from a StreamJob. | A normal Job has no stream queue. |
+| Guidance | Reason |
+|---------------------------------------------------------------------------------|-------------------------------------------------------------------------------|
+| Read input from `context` and write intermediate results to `context`. | A multi-Step Job passes data through the same context. |
+| Write the final result to `context.response`. | Services and clients consume the standard `Response`. |
+| Do not store request-scoped state on a Step instance. | A Step is rebuilt for every Job call, and stateless Steps are easier to test. |
+| A background loop that supports interruption should check `context.stop_event`. | `BackgroundJob.close()` relies on the stop event for graceful shutdown. |
+| Call `add_stream_string()` only from a StreamJob. | A normal Job has no stream queue. |
### 9.5 Unit Test Example
@@ -600,8 +613,8 @@ async def test_uppercase_step():
## 10. Adding a Job
-A Job usually requires no new Python class; configure existing Steps instead. Add a new Job backend only when a new execution
-model is required.
+A Job usually requires no new Python class; configure existing Steps instead. Add a new Job backend only when a new
+execution model is required.
### 10.1 Adding a Normal Request Job
@@ -736,11 +749,11 @@ jobs:
Characteristics of a background Job:
-| Characteristic | Description |
-|---|---|
-| Not externally exposed | `BackgroundJob.__init__()` forces `enable_serve=False`. |
-| Has a supervisor | Restarts with exponential backoff after an exception by default. |
-| Has a stop event | Notifies the loop to exit during close. |
+| Characteristic | Description |
+|---------------------------------|--------------------------------------------------------------------|
+| Not externally exposed | `BackgroundJob.__init__()` forces `enable_serve=False`. |
+| Has a supervisor | Restarts with exponential backoff after an exception by default. |
+| Has a stop event | Notifies the loop to exit during close. |
| Suitable for watching/consuming | File watching, queue consumption, and periodic long-running loops. |
### 10.5 Adding a Cron Job
@@ -767,14 +780,14 @@ An invalid `cron` expression fails at startup.
Most use cases require only a new Step plus a YAML Job. Consider adding `reme/components/job/*.py` only in these cases:
-| Requirement | New Job class? |
-|---|---|
-| Add a business command | No; use `backend: base`. |
-| Chain existing steps | No; use `steps:`. |
-| Need SSE/streaming output | No; use `backend: stream`. |
-| Need a background loop | No; use `backend: background`. |
-| Need cron scheduling | No; use `backend: cron`. |
-| Need entirely new scheduling, concurrency, or transaction semantics | Yes; add a Job backend. |
+| Requirement | New Job class? |
+|---------------------------------------------------------------------|--------------------------------|
+| Add a business command | No; use `backend: base`. |
+| Chain existing steps | No; use `steps:`. |
+| Need SSE/streaming output | No; use `backend: stream`. |
+| Need a background loop | No; use `backend: background`. |
+| Need cron scheduling | No; use `backend: cron`. |
+| Need entirely new scheduling, concurrency, or transaction semantics | Yes; add a Job backend. |
Minimal shape of a new Job backend:
diff --git a/docs/en/memory_as_file.md b/docs/en/memory_as_file.md
index da41506c..5202887a 100644
--- a/docs/en/memory_as_file.md
+++ b/docs/en/memory_as_file.md
@@ -6,37 +6,39 @@ ReMe's core idea is **Memory as File, File as Memory**.
-**Memory as File**: long-term memory is not hidden in a black-box database. It lives in Markdown files, resource files, and
-index snapshots under the workspace. Users and agents can directly read, write, move, and delete those files.
+**Memory as File**: long-term memory is not hidden in a black-box database. Its source material and readable memories
+live in user-owned files under the workspace. Users and agents can directly read, write, move, and delete those files;
+indexes and snapshots under `metadata/` are derived state that can be rebuilt.
-**File as Memory**: each file is more than ordinary text. It is an indexable, linkable, and evolvable memory node. ReMe parses
-frontmatter, body chunks, and wikilink edges from files and organizes them into retrieval indexes and a graph.
+**File as Memory**: each file is more than ordinary text. It is an indexable, linkable, and evolvable memory node. ReMe
+parses frontmatter, body chunks, and wikilink edges from files and organizes them into retrieval indexes and a graph.
In other words, files are both a human-readable interface and an operational interface for agents. Directory structure
carries the memory layers, while Markdown syntax expresses content, metadata, and relationships.
## Design Goals
-ReMe represents memory as files not merely for convenient storage, but to give long-term memory several essential properties:
+ReMe represents memory as files not merely for convenient storage, but to give long-term memory several essential
+properties:
-| Goal | Meaning |
-|---|---|
-| Readable | Users can open the workspace directly and read daily notes, digest nodes, and source material like ordinary notes. |
-| Editable | Users and agents can correct, extend, move, or delete memory with file operations, without a specialized database client. |
-| Traceable | Long-term conclusions in digest can point back to daily, resource, or session files from a Sources section. |
-| Portable | The workspace is an ordinary directory. Markdown, JSONL, YAML, and resource files can be backed up, synchronized, versioned, or moved to other tools. |
-| Indexable | Although the files are plain text, ReMe parses frontmatter, chunks, and wikilinks to build a retrieval index and file graph. |
-| Collaborative | Humans judge and correct; agents organize, link, and retrieve. Both operate on the same files. |
+| Goal | Meaning |
+|---------------|-------------------------------------------------------------------------------------------------------------------------------------------------------|
+| Readable | Users can open the workspace directly and read daily notes, digest nodes, and source material like ordinary notes. |
+| Editable | Users and agents can correct, extend, move, or delete memory with file operations, without a specialized database client. |
+| Traceable | Long-term conclusions in digest can point back to daily, resource, or session files from a Sources section. |
+| Portable | The workspace is an ordinary directory. Markdown, JSONL, YAML, and resource files can be backed up, synchronized, versioned, or moved to other tools. |
+| Indexable | Although the files are plain text, ReMe parses frontmatter, chunks, and wikilinks to build a retrieval index and file graph. |
+| Collaborative | Humans judge and correct; agents organize, link, and retrieve. Both operate on the same files. |
-ReMe memory is therefore neither a hidden database record nor a prompt fragment visible only to an LLM. It is first a file
-owned by the user and only then indexed by the system for retrieval.
+ReMe memory is therefore neither a hidden database record nor a prompt fragment visible only to an LLM. It is first a
+file owned by the user and only then indexed by the system for retrieval.
## Memory Layers
A ReMe workspace divides memory into four layers:
```text
-raw input -> session/ + resource/
+source records -> session/ + resource/
working memory -> daily/
long memory -> digest/
system state -> metadata/
@@ -44,19 +46,23 @@ system state -> metadata/
Each layer solves a different problem.
-`session/` and `resource/` preserve raw input. Their purpose is to retain the original situation: conversations, agent
-sessions, uploaded material, web pages, and reports remain intact as evidence for later verification.
+`session/` and `resource/` preserve source records. Files under `resource/` remain unchanged at their original path.
+Standard Auto Memory records retain conversation messages while intentionally omitting tool-result and base64 data
+blocks; this keeps recalled output and binary payloads from masquerading as user-provided evidence. Generated Agent
+runtime state instead lives under `mem_session/`.
-`daily/` is the lightly processed layer. It organizes the day's conversations and resources into more readable daily notes:
-what happened, which conclusions were reached, which follow-up tasks remain, and where the source material lives. Daily does
-not aim for final abstraction; it is closer to a workbench for the day.
+`daily/` is the lightly processed layer. It organizes the day's conversations and resources into more readable daily
+notes:
+what happened, which conclusions were reached, which follow-up tasks remain, and where the source material lives. Daily
+does not aim for final abstraction; it is closer to a workbench for the day.
`digest/` is the deeply processed layer. It stores memory nodes that can be reused over time, such as user preferences,
project background, procedural experience, conceptual knowledge, and decision precedents. Digest should not merely copy
daily. It should merge recurring facts, methods, and relationships into more stable descriptions.
-`metadata/` is the system index layer. It stores runtime state such as the file catalog, chunk index, and graph snapshots.
-Users normally do not edit this content manually. The actual editing surface is `daily/`, `digest/`, and, when necessary,
+`metadata/` is the system index layer. It stores runtime state such as the file catalog, chunk index, and graph
+snapshots. Users normally do not edit this content manually. The actual editing surface is `daily/`, `digest/`, and,
+when necessary,
`resource/`.
These layers let ReMe preserve both the original situation and its abstraction: daily reconstructs what happened, while
@@ -73,21 +79,23 @@ The corresponding automatic flows are [Auto Memory](./auto_memory.md), [Auto Res
```text
/
├── metadata/ # system index layer; persistent indexes, graph, catalogs; not a manual editing surface
-├── session/ # raw input layer; original conversations and agent sessions
+├── session/ # source-record layer; source conversations
│ ├── dialog/
-│ │ └── .jsonl # conversation messages saved by auto_memory
-│ ├── agentscope/
-│ │ └── .jsonl
+│ │ └── .jsonl # source messages saved by auto_memory
│ └── claude_code/
-│ └── .jsonl
-├── resource/ # raw input layer; original external material
+│ └── .jsonl # ReMe copy used by auto_memory_cc
+├── mem_session/ # generated Agent wrapper sessions/config, not user memory
+│ ├── agentscope/
+│ ├── claude_config/
+│ └── codex/
+├── resource/ # source-record layer; original external material
+│ ├── . # root-level input uses today's date
│ └── YYYY-MM-DD/
-│ └── .
+│ └── . # dated input uses the directory date
├── daily/ # lightly processed layer; facts, conversation summaries, and resource interpretations by date
│ ├── YYYY-MM-DD.md # index page for the day
│ └── YYYY-MM-DD/
-│ ├── .md # daily note distilled from a conversation
-│ ├── .md # daily note distilled from a resource
+│ ├── .md # topic-named conversation or resource card
│ └── interests.yaml # proactive interest topics generated by auto_dream
└── digest/ # deeply processed layer; reusable personal facts, procedures, and knowledge nodes
├── personal/
@@ -103,17 +111,21 @@ Typical flows:
```text
conversation
-> session/dialog/.jsonl
- -> daily/YYYY-MM-DD/.md
+ -> daily/YYYY-MM-DD/.md
-> digest/personal | digest/procedure | digest/wiki
external resource
- -> resource/YYYY-MM-DD/.
- -> daily/YYYY-MM-DD/.md
+ -> resource/[YYYY-MM-DD/].
+ -> daily/YYYY-MM-DD/.md
-> digest/wiki | digest/procedure
```
-The first two steps focus on recording and organizing; the final step focuses on long-term distillation. `auto_memory` and
-`auto_resource` generate daily notes from raw input, and `auto_dream` extracts and integrates digest nodes from daily.
+The first two steps focus on recording and organizing; the final step focuses on long-term distillation. `auto_memory`
+and
+`auto_resource` generate daily notes from source input, and `auto_dream` extracts and integrates digest nodes from
+daily. The generated daily filename comes from validated frontmatter `name`; `session_id`, `source_conversation`, and
+`source_resource`
+provide stable provenance and lookup identity instead of determining the filename.
## Markdown Format
@@ -146,8 +158,8 @@ source_conversation: [[session/dialog/abc.jsonl]]
---
```
-The current code recognizes `name` and `description` explicitly. Other fields are preserved as additional metadata. The write
-interface merges `name`, `description`, and `metadata` into frontmatter.
+The current code recognizes `name` and `description` explicitly. Other fields are preserved as additional metadata. The
+write interface merges `name`, `description`, and `metadata` into frontmatter.
Treat frontmatter as a node-level summary and the body as evidence, explanation, and relationships. For example:
@@ -165,7 +177,7 @@ Apply this preference when following [[digest/procedure/technical-documentation.
## Sources
-- [[daily/2026-06-20/session-a.md]]
+This preference was recorded in [[daily/2026-06-20/documentation-style.md]], which captures the user's repeated guidance.
```
This has three benefits:
@@ -174,8 +186,8 @@ This has three benefits:
2. The body can carry fuller facts, conditions, counterexamples, and sources.
3. Ordinary wikilinks can be parsed by the graph and maintained when files move.
-Frontmatter is best for stable, short, structured fields; the body is best for explanations meant for people. Do not put long
-body text into YAML fields.
+Frontmatter is best for stable, short, structured fields; the body is best for explanations meant for people. Do not put
+long body text into YAML fields.
### Wikilink
@@ -197,13 +209,13 @@ ReMe wikilinks use **literal path semantics**:
ReMe does not append `.md` automatically, search by filename, or automatically resolve folder notes. Use complete
workspace-relative paths with their extensions.
-Ordinary Markdown links such as `[label](../wiki/example.md)` do not create `FileLink` edges and are not rewritten by move or
-retarget operations.
+Ordinary Markdown links such as `[label](../wiki/example.md)` do not create `FileLink` edges and are not rewritten by
+move or retarget operations.
Anchors such as `#L9`, `#L9-L10`, and `#L9-L10,L15-L20` remain ordinary `target_anchor` strings in the graph. The graph
-parser does not validate line-anchor syntax, so values such as `#L0`, `#L10-L9`, and `#L9,` are also stored. The `read` job
-does not interpret an anchor appended to `path`; use the separate 1-based, inclusive `start_line` and `end_line` arguments to
-read a range, for example `read(path="digest/wiki/solar.md", start_line=9, end_line=10)`.
+parser does not validate line-anchor syntax, so values such as `#L0`, `#L10-L9`, and `#L9,` are also stored. The `read`
+job does not interpret an anchor appended to `path`; use the separate 1-based, inclusive `start_line` and `end_line`
+arguments to read a range, for example `read(path="digest/wiki/solar.md", start_line=9, end_line=10)`.
Wikilinks support these behaviors:
@@ -224,9 +236,8 @@ FileLink
```
Older documents containing wrappers such as `related:: [[path]]`,
-`- related:: [[path]]`, or `[related:: [[path]]]` remain readable. ReMe
-ignores the surrounding text and indexes the inner `[[path]]` as an ordinary
-link. After upgrading from a version that stored typed links, run `reme reindex`
+`- related:: [[path]]`, or `[related:: [[path]]]` remain readable. ReMe ignores the surrounding text and indexes the
+inner `[[path]]` as an ordinary link. After upgrading from a version that stored typed links, run `reme reindex`
once to rebuild the derived graph without the removed relationship field.
### Sources and Relationships
@@ -238,8 +249,8 @@ A Sources section records where a long-term memory came from:
```markdown
## Sources
-- [[daily/2026-06-20/session-a.md]]
-- [[resource/2026-06-20/report.pdf]]
+The preference was observed in [[daily/2026-06-20/documentation-style.md]], and the supporting report evidence is retained in
+[[resource/2026-06-20/report.pdf]].
```
A conceptual relationship link explains which other long-term memories relate to the node. Weave it into natural prose:
@@ -255,16 +266,16 @@ This analysis extends [[digest/wiki/solar-supply-chain.md]], follows
Because memory is stored as files, users can edit the workspace directly, while agents can read and write the same files
through ReMe's file tools. Both follow the same conventions:
-| Operation | Guidance |
-|---|---|
-| Add memory | Write to the appropriate directory, use frontmatter for Markdown, and prefer complete workspace-relative wikilinks. |
-| Edit a body | Preserve existing sources and important wikilinks. When correcting an old conclusion, explain how the new material changes the previous judgment. |
-| Move a file | ReMe's move tool rewrites old paths in inbound edges by default. After a manual move, inspect inbound links again. |
+| Operation | Guidance |
+|---------------|---------------------------------------------------------------------------------------------------------------------------------------------------|
+| Add memory | Write to the appropriate directory, use frontmatter for Markdown, and prefer complete workspace-relative wikilinks. |
+| Edit a body | Preserve existing sources and important wikilinks. When correcting an old conclusion, explain how the new material changes the previous judgment. |
+| Move a file | ReMe's move tool rewrites old paths in inbound edges by default. After a manual move, inspect inbound links again. |
| Delete a file | Check inbound links first. ReMe's delete tool returns source files that still point to the target, making dangling references easier to clean up. |
-| Edit metadata | Use frontmatter for short fields. When the body changes substantially, update `description` as well. |
+| Edit metadata | Use frontmatter for short fields. When the body changes substantially, update `description` as well. |
-A practical rule is: **an agent may rewrite the wording, but it must not lose evidence edges**. In particular, Sources entries
-and existing digest-to-digest wikilinks are the basis for traceable and extensible long-term memory.
+A practical rule is: **an agent may rewrite the wording, but it must not lose evidence edges**. In particular, Sources
+entries and existing digest-to-digest wikilinks are the basis for traceable and extensible long-term memory.
## Path Semantics
@@ -272,7 +283,7 @@ All file tools and wikilinks use workspace-relative paths as their basic unit:
```text
digest/wiki/solar.md
-daily/2026-06-20/session-a.md
+daily/2026-06-20/documentation-style.md
resource/2026-06-20/report.pdf
```
@@ -284,16 +295,16 @@ Recommended practices:
1. Include `.md` when linking a Markdown file.
2. Use the complete source path when linking from digest to daily or resource.
3. Rename or move files through ReMe's move tool whenever possible to avoid stale paths.
-4. Put external source material under `resource/YYYY-MM-DD/...` and long-term abstractions under `digest/...`. Do not put
- raw source material directly into digest.
+4. Put external source material under `resource/YYYY-MM-DD/...` and long-term abstractions under `digest/...`. Do not
+ put raw source material directly into digest.
-Explicit path semantics sacrifice a little convenience when writing by hand, but provide predictability, portability, and
-automatic maintainability.
+Explicit path semantics sacrifice a little convenience when writing by hand, but provide predictability, portability,
+and automatic maintainability.
## Memory Chunking
-Memory chunking divides a file into retrievable fragments. ReMe does not split Markdown at fixed lengths by default; it tries
-to preserve semantic structure.
+Memory chunking divides a file into retrievable fragments. ReMe does not split Markdown at fixed lengths by default; it
+tries to preserve semantic structure.
This section explains how files become retrieval chunks. For index updates, BM25, vector recall, and link expansion, see
[Memory Search](./memory_search.md).
@@ -308,8 +319,8 @@ Document
chunk 1 | chunk 2 | chunk 3 | ...
```
-This is simple, but it can cut headings, tables, code blocks, lists, and `[[wikilinks]]` in the middle. After a match, the
-agent often sees only an isolated fragment without knowing its section or relationship to other memory nodes.
+This is simple, but it can cut headings, tables, code blocks, lists, and `[[wikilinks]]` in the middle. After a match,
+the agent often sees only an isolated fragment without knowing its section or relationship to other memory nodes.
ReMe chunking is closer to splitting memory by file structure:
@@ -375,5 +386,5 @@ Matched body fragment
This lets the agent see not only an isolated paragraph but also its structural position in the source file.
-Non-Markdown files use `DefaultFileChunker` by default. It splits by byte size and preserves a small overlap. For Markdown,
-the chunker also avoids cutting `[[wikilinks]]` in the middle.
+Non-Markdown files use `DefaultFileChunker` by default. It splits by byte size and preserves a small overlap. For
+Markdown, the chunker also avoids cutting `[[wikilinks]]` in the middle.
diff --git a/docs/en/memory_search.md b/docs/en/memory_search.md
index 5f2c3784..3beb80b4 100644
--- a/docs/en/memory_search.md
+++ b/docs/en/memory_search.md
@@ -1,8 +1,10 @@
# Memory Search
-Memory Search is ReMe's memory retrieval entry point. It continuously builds files under `daily/`, `digest/`, and `resource/`
-into a searchable chunk index and wikilink graph. At query time, it first recalls the most relevant fragments and then expands
-context along the bidirectional links of the files containing those fragments.
+Memory Search is ReMe's memory retrieval entry point. The default background loop continuously builds Markdown under
+`daily/` and `digest/` into a searchable chunk index and wikilink graph. At query time, it first recalls the most
+relevant fragments and then expands context along the bidirectional links of the files containing those fragments.
+`reme reindex` has a broader rebuild scope that also scans `resource/` and JSONL; it is intentionally different from the
+live watcher.
@@ -21,14 +23,17 @@ workspace files
## What It Searches
-The default `index_update_loop` watches three memory directories:
+The default `index_update_loop` watches two memory directories:
- `daily_dir`: daily working memory and session memory cards generated by Auto Memory.
- `digest_dir`: long-term distilled digest nodes.
-- `resource_dir`: external resources or imported material.
-The default suffixes are `md` and `jsonl`. Markdown uses the `markdown` chunker, which parses frontmatter, heading structure,
-and `[[wikilinks]]`. JSONL uses the `default` chunker and creates overlapping chunks by byte size.
+The live watcher handles only the `md` suffix. A separate `resource_watch_loop` watches `resource_dir`, and Auto
+Resource turns those inputs into daily cards that enter the live index. When `reme reindex` is run manually, its
+configuration scans
+`daily_dir`, `digest_dir`, and `resource_dir` for `md` and `jsonl`; Markdown uses the `markdown` chunker and JSONL uses
+the
+`jsonl` chunker.
## How the Index Is Built
@@ -39,8 +44,8 @@ The background Job `index_update_loop` maintains the index using configuration f
```yaml
index_update_loop:
backend: background
- watch_dirs: [ daily_dir, digest_dir, resource_dir ]
- watch_suffixes: [ md, jsonl ]
+ watch_dirs: [daily_dir, digest_dir]
+ watch_suffixes: [md]
steps:
- backend: init_changes_step
monitor_type: file_store
@@ -54,9 +59,9 @@ index_update_loop:
`FileNode.st_mtime` values already stored in `file_store`, calculates added, modified, and deleted changes, and passes
`context["changes"]` to `update_index_step`.
-While the service is running, `watch_changes_step` takes over. It uses `watchfiles.awatch()` to watch the same directories,
-groups file events within a quiet window, and uses `coalesce_changes()` to collapse repeated events for the same path into one
-stable batch of changes.
+While the service is running, `watch_changes_step` takes over. It uses `watchfiles.awatch()` to watch the same
+directories, groups file events within a quiet window, and uses `coalesce_changes()` to collapse repeated events for the
+same path into one stable batch of changes.
`update_index_step` performs the actual index writes:
@@ -66,13 +71,14 @@ stable batch of changes.
4. For a deleted file, remove its records from `file_store`, `keyword_index`, and `file_graph`.
5. When changes exist, dump state to `metadata/` so it can be restored on the next startup.
-The Markdown chunker parses YAML frontmatter, heading structure, and wikilinks into `FileNode`, `FileChunk`, and `FileLink`
+The Markdown chunker parses YAML frontmatter, heading structure, and wikilinks into `FileNode`, `FileChunk`, and
+`FileLink`
objects. For detailed chunking rules, see [Memory as File](./memory_as_file.md#memory-chunking).
### Index Optimization
-Both BM25 and the FAISS HNSW vector index use tombstone markers instead of physical removal when deleting nodes;
-too many tombstones degrade search performance. An idle-time optimization mechanism is built in—the `optimize_index_cron`
+Both BM25 and the FAISS HNSW vector index use tombstone markers instead of physical removal when deleting nodes; too
+many tombstones degrade search performance. An idle-time optimization mechanism is built in—the `optimize_index_cron`
scheduled job compacts tombstones and rebuilds indexes during off-peak hours:
```yaml
@@ -100,12 +106,12 @@ file_store:
It combines three kinds of capability:
-| Part | Default state | Purpose |
-|---|---|---|
-| `file_chunks` | Enabled | Store `FileChunk` text, line numbers, scores, and optional embeddings. |
-| `keyword_index.default` | Enabled | BM25 inverted index where chunk ID is the document ID. |
-| `file_graph.default` | Enabled | Store `FileNode` objects and wikilink edges. |
-| `embedding_store` | Disabled | When enabled, generate embeddings for chunks and support vector recall. |
+| Part | Default state | Purpose |
+|-------------------------|---------------|-------------------------------------------------------------------------|
+| `file_chunks` | Enabled | Store `FileChunk` text, line numbers, scores, and optional embeddings. |
+| `keyword_index.default` | Enabled | BM25 inverted index where chunk ID is the document ID. |
+| `file_graph.default` | Enabled | Store `FileNode` objects and wikilink edges. |
+| `embedding_store` | Disabled | When enabled, generate embeddings for chunks and support vector recall. |
Out of the box, search therefore uses primarily BM25 plus link expansion. After setting `embedding_store: default`,
`SearchStep` runs vector and keyword recall together. Additionally, switching the `file_store` `backend` from `local` to
@@ -123,10 +129,12 @@ search:
query: string
limit: integer
min_score: number
+ start_date: string
+ end_date: string
steps:
- backend: search_step
vector_weight: 0.7
- candidate_multiplier: 3.0
+ candidate_multiplier: 5.0
expand_links: true
max_links_per_direction: 10
```
@@ -137,11 +145,17 @@ Call it with:
reme search query="recent discussions about indexing" limit=5
```
+Use `start_date` and `end_date` for inclusive `YYYY-MM-DD` filtering:
+
+```bash
+reme search query="index regression" start_date=2026-06-01 end_date=2026-06-20 limit=10
+```
+
`search_step` executes in this order:
```mermaid
flowchart LR
- A["query + limit"] --> B["candidates = limit * candidate_multiplier"]
+ A["query + limit"] --> B["candidates = min(200, limit * candidate_multiplier)"]
B --> C["file_store.vector_search(...)"]
B --> D["file_store.keyword_search(...)"]
C --> E["RRF fusion"]
@@ -152,17 +166,17 @@ flowchart LR
H --> I["Response.answer + metadata"]
```
-If only BM25 has results, the BM25 ranking is returned directly. If only vector search has results, the vector ranking is
-returned directly. When both have results, they are fused with RRF. RRF does not compare BM25 and cosine scores directly; it
-compares ranks in the two result lists:
+If only BM25 has results, the BM25 ranking is returned directly. If only vector search has results, the vector ranking
+is returned directly. When both have results, they are fused with RRF. RRF does not compare BM25 and cosine scores
+directly; it compares ranks in the two result lists:
```text
fused_score = vector_weight / (60 + vector_rank)
+ keyword_weight / (60 + keyword_rank)
```
-The default `vector_weight=0.7` gives semantic recall more weight when embeddings are enabled, while keyword search can still
-promote chunks with exact term matches.
+The default `vector_weight=0.7` gives semantic recall more weight when embeddings are enabled, while keyword search can
+still promote chunks with exact term matches.
## How BM25 Works
@@ -174,12 +188,14 @@ promote chunks with exact term matches.
- The inverted index records which chunks contain each token and its term frequency within each chunk.
- A query scores only the posting lists matching its tokens and returns the highest-scoring chunk IDs.
-When a file changes, `LocalFileStore.upsert()` first removes the BM25 documents corresponding to the file's old `chunk_ids`
+When a file changes, `LocalFileStore.upsert()` first removes the BM25 documents corresponding to the file's old
+`chunk_ids`
and then adds the new chunk text. Deletion is lazy; the index can later be compacted with optimize.
## Progressive Expansion
-"Progressive" in Memory Search does not mean putting the entire repository into one result. Retrieval expands in three layers:
+"Progressive" in Memory Search does not mean putting the entire repository into one result. Retrieval expands in three
+layers:
1. Chunk recall: return only the `limit` most relevant text fragments.
2. File location: each result includes `path:start_line-end_line`. Pass the path and line bounds separately as `path`,
@@ -198,8 +214,8 @@ matched chunk
-> render neighbor path, name, description, and anchor
```
-This keeps search results short while still showing which long-term nodes, resources, or other daily notes a memory connects
-to. If a result is worth pursuing, use `read path=...` to open the source or
+This keeps search results short while still showing which long-term nodes, resources, or other daily notes a memory
+connects to. If a result is worth pursuing, use `read path=...` to open the source or
`traverse path=... depth=2` to continue along the wikilink graph.
## Return Format
@@ -213,7 +229,7 @@ to. If a result is worth pursuing, use `read path=...` to open the source or
Typical text structure:
```text
-========== daily/2026-06-20/session-a.md:12-28 [score=0.0317 keyword=4.8120] ==========
+========== daily/2026-06-20/retrieval-regression.md:12-28 [score=0.0317 keyword=4.8120] ==========
...matched memory fragment...
outlinks (2):
-> digest/indexing.md name="Indexing" description="..."
@@ -221,5 +237,5 @@ Typical text structure:
<- daily/2026-06-19.md name="..."
```
-`counts` reports how many vector and keyword candidates were recalled and how many results were ultimately returned. With
-embeddings disabled by default, `vector` is usually `0` and `hybrid` is `false`.
+`counts` reports how many vector and keyword candidates were recalled and how many results were ultimately returned.
+With embeddings disabled by default, `vector` is usually `0` and `hybrid` is `false`.
diff --git a/docs/en/proactive.md b/docs/en/proactive.md
index 7b13bd6d..19c0b38d 100644
--- a/docs/en/proactive.md
+++ b/docs/en/proactive.md
@@ -1,17 +1,17 @@
# Proactive
-`proactive` is ReMe's interface for reading proactive memory. It does not reanalyze daily notes or call an LLM. It only reads
-the current day's interest topics written by `auto_dream`:
+`proactive` is ReMe's interface for reading proactive memory. It does not reanalyze daily notes or call an LLM. It only
+reads the current day's interest topics written by `auto_dream`:
```text
daily//interests.yaml
```
-A host agent can use it to learn "what is worth proactive attention today," then decide whether to remind the user, ask a
-follow-up question, recommend a next step, or produce a proactive insight.
+A host agent can use it to learn "what is worth proactive attention today," then decide whether to remind the user, ask
+a follow-up question, recommend a next step, or produce a proactive insight.
-`interests.yaml` is generated by the Topics stage of [Auto Dream](./auto_dream.md). `proactive` only reads and exposes the
-result.
+`interests.yaml` is generated by the Topics stage of [Auto Dream](./auto_dream.md). `proactive` only reads and exposes
+the result.
## Configuration
@@ -34,10 +34,10 @@ proactive:
Parameters:
-| Parameter | Purpose |
-|---|---|
-| `date` | Date to read in `YYYY-MM-DD` format. When empty, use today in the application's timezone. |
-| `include_content` | Whether to return the raw YAML in the answer and metadata. Defaults to `true`. |
+| Parameter | Purpose |
+|-------------------|-------------------------------------------------------------------------------------------|
+| `date` | Date to read in `YYYY-MM-DD` format. When empty, use today in the application's timezone. |
+| `include_content` | Whether to return the raw YAML in the answer and metadata. Defaults to `true`. |
## Input Contract
@@ -67,15 +67,15 @@ When the file is read successfully, `proactive_step` returns `summary` and `topi
`include_content=true`, the answer also contains `content`. The same result fields remain available in standard response
metadata:
-| Field | Description |
-|---|---|
-| `date` | The date actually read. |
-| `path` | `daily//interests.yaml`. |
-| `topics` | Parsed topic list. |
+| Field | Description |
+|-----------|------------------------------------------------------|
+| `date` | The date actually read. |
+| `path` | `daily//interests.yaml`. |
+| `topics` | Parsed topic list. |
| `content` | Raw YAML; returned only when `include_content=true`. |
-| `skipped` | `true` when the file does not exist. |
-| `error` | Read or parse error. |
-| `summary` | Short summary. |
+| `skipped` | `true` when the file does not exist. |
+| `error` | Read or parse error. |
+| `summary` | Short summary. |
When the file exists and parses successfully, the answer is structured data. For example:
@@ -135,21 +135,21 @@ daily notes
The responsibilities are divided as follows. For the complete Extract, Integrate, Topics, and Finish flow, see
[Auto Dream](./auto_dream.md):
-| Module | Responsibility |
-|---|---|
-| `dream_extract_step` | Extract topic candidates from changed daily inputs. |
-| `dream_topics_step` | Deduplicate, select, and write `interests.yaml`. |
-| `proactive_step` | Read `interests.yaml` and expose it to the host agent. |
+| Module | Responsibility |
+|----------------------|--------------------------------------------------------|
+| `dream_extract_step` | Extract topic candidates from changed daily inputs. |
+| `dream_topics_step` | Deduplicate, select, and write `interests.yaml`. |
+| `proactive_step` | Read `interests.yaml` and expose it to the host agent. |
-`proactive` does not modify files, update a catalog, or decide whether the user should be interrupted. It only provides the
-day's topic material. The caller's product policy determines whether, when, and in what tone to push it to the user.
+`proactive` does not modify files, update a catalog, or decide whether the user should be interrupted. It only provides
+the day's topic material. The caller's product policy determines whether, when, and in what tone to push it to the user.
## Failure Modes
-| Scenario | Behavior |
-|---|---|
-| `interests.yaml` does not exist | `success=true`, `skipped=true`, `topics=[]`. |
-| YAML cannot be read or parsed | `success=false`; the answer contains an error summary. |
-| YAML exists but has no valid topics | `success=true`, `topics=[]`. |
+| Scenario | Behavior |
+|-------------------------------------|--------------------------------------------------------|
+| `interests.yaml` does not exist | `success=true`, `skipped=true`, `topics=[]`. |
+| YAML cannot be read or parsed | `success=false`; the answer contains an error summary. |
+| YAML exists but has no valid topics | `success=true`, `topics=[]`. |
Callers should therefore check `success` first, then `skipped`, and finally whether `topics` is empty.
diff --git a/docs/en/quick_start.md b/docs/en/quick_start.md
index d0e31036..2bc7a806 100644
--- a/docs/en/quick_start.md
+++ b/docs/en/quick_start.md
@@ -18,8 +18,8 @@ cd ReMe
pip install -e ".[core]"
```
-Installing the `core` extra is recommended. The current code imports the AgentScope wrapper, and self-evolving memory also
-depends on it.
+Installing the `core` extra is recommended. The current code imports the AgentScope wrapper, and self-evolving memory
+also depends on it.
To use agent workflows such as `auto_memory`, `auto_resource`, and `auto_dream`, configure an LLM:
@@ -51,10 +51,15 @@ reme start service.port=8181
```bash
reme version
reme health_check
-reme list
+reme help
```
-`reme list` lists server actions. Ordinary commands invoke server Jobs over HTTP.
+`reme help` lists server actions. Ordinary commands invoke server Jobs over HTTP.
+
+When the package includes the web build, open for ReMe Studio. It uses the same service to
+browse, edit, and search the workspace and inspect the digest wikilink graph. Disable it with
+`service.web_enabled=false`, or provide a custom build with `service.web_static_dir` / `REME_WEB_STATIC_DIR`. The Job
+API still starts if no web build is found.
---
@@ -65,7 +70,8 @@ The default workspace is `.reme/` under the current directory. It is created aut
```text
.reme/
├── metadata/ # persistent indexes, graph, catalogs, and related state
-├── session/ # agent sessions and original conversations
+├── session/ # source conversation records
+├── mem_session/ # generated Agent wrapper sessions/config
├── resource/ # external resources
├── daily/ # daily notes
└── digest/ # long-term memory
@@ -91,12 +97,13 @@ reme write \
description="Example memory for the quick start" \
content="# Quick Start Demo
-ReMe indexes Markdown under the daily, digest, and resource directories.
+The default live watcher indexes Markdown under the daily and digest directories.
Related link: [[digest/wiki/search-demo.md]]"
```
-`path` is relative to the workspace. A missing suffix is automatically completed with `.md`. For Markdown files, `name` and
+`path` is relative to the workspace. A missing suffix is automatically completed with `.md`. For Markdown files, `name`
+and
`description` are written to frontmatter.
The background watcher builds the index automatically. You can also rebuild it manually:
@@ -117,8 +124,8 @@ Read:
reme read path=digest/wiki/quick-start-demo start_line=1 end_line=20
```
-With the default configuration, retrieval is primarily BM25 plus wikilink graph expansion. Vector retrieval is supported by
-the code, but the embedding store is disabled by default. For the full retrieval flow, see
+With the default configuration, retrieval is primarily BM25 plus wikilink graph expansion. Vector retrieval is supported
+by the code, but the embedding store is disabled by default. For the full retrieval flow, see
[Memory Search](./memory_search.md).
---
@@ -132,7 +139,13 @@ reme frontmatter_read path=digest/wiki/quick-start-demo
reme frontmatter_update path=digest/wiki/quick-start-demo metadata='{"tags":["demo"]}'
```
-The name `list` is used by the CLI to list actions, so the file-listing Job must be called over HTTP:
+The file-listing Job can be called directly from the CLI:
+
+```bash
+reme list path=digest recursive=true limit=50
+```
+
+The equivalent HTTP call is:
```bash
curl -s http://127.0.0.1:2333/list \
@@ -161,7 +174,8 @@ reme auto_memory \
memory_hint="Record the user's preference"
```
-After placing external material under `resource/YYYY-MM-DD/`, the default background task watches
+After placing external material under `resource/YYYY-MM-DD/` or directly under `resource/`, the default background task
+watches
`md/txt/json/jsonl/csv/yaml/html`. You can also trigger processing manually:
```bash
@@ -175,7 +189,8 @@ reme auto_dream date=2026-06-20
reme proactive date=2026-06-20
```
-These flows require a working LLM. Without an LLM configuration, start with basic capabilities such as `write`, `read`, and
+These flows require a working LLM. Without an LLM configuration, start with basic capabilities such as `write`, `read`,
+and
`search`.
For more detail, see [Auto Memory](./auto_memory.md), [Auto Resource](./auto_resource.md),
diff --git a/docs/en/reme-blog.md b/docs/en/reme-blog.md
index 516bd7d4..32fd8b56 100644
--- a/docs/en/reme-blog.md
+++ b/docs/en/reme-blog.md
@@ -71,7 +71,7 @@ When writing an article, refer to [[digest/procedure/Technical content writing p
## Sources
-- [[daily/2026-08-07/content-discussion.md]]
+This preference was observed in [[daily/2026-08-07/content-discussion.md]], which records the user's writing guidance.
```
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.
@@ -90,14 +90,17 @@ 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/`.
+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 retaining a source conversation record 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
+session/dialog/project-a.jsonl Source conversation record
+daily/2026-08-07/login-refactor-decision.md Content-named memory card
+daily/2026-08-07.md Daily index, providing an overview
```
+`session_id` remains in the card's frontmatter for stable lookup and provenance; the filename comes from the Agent-generated
+topic/event `name`, so it does not have to match the session ID.
+
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.
@@ -136,7 +139,9 @@ Suppose conversations and external materials give you three pieces of informatio
- 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:
+By default, Auto Dream looks at the two most recent days ending at the target date and sends only daily files changed since
+the previous run to extraction. It merges cross-file evidence for the same abstraction and keeps only the strongest reusable
+memories within a default cap of five units, then 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;
@@ -159,7 +164,8 @@ follow the “add regression tests first” convention in [[digest/personal/Team
## Sources
-- [[daily/2026-08-07/build-debug.md|Build troubleshooting record]] provides the root cause and applicable scenarios.
+The root cause and applicable scenarios were documented in
+[[daily/2026-08-07/build-debug.md|Build troubleshooting record]].
```
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.
@@ -170,7 +176,10 @@ Knowledge evolves and links are created in the same workflow. Relationships are
-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.
+Markdown is easy for people to read, but if files are merely piled into directories, agents still struggle to find them
+quickly. The default live index watches Markdown under `daily/` and `digest/`. A separate resource workflow watches
+`resource/` and turns those files into daily cards that enter the same index. For a full rebuild from existing files,
+`reme reindex` also scans `resource/` and JSONL.
A Markdown file is parsed into:
@@ -299,7 +308,10 @@ That is what ReMe sets out to do: **make memory not only persistent, but continu
## 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.
+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. The default HTTP service can also serve ReMe Studio at the same address for browsing,
+editing, and searching the workspace and inspecting the digest wikilink graph. 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 |
|-------|-------------------------|--------------------------------|
diff --git a/docs/en/reme_scene.md b/docs/en/reme_scene.md
index d7ce86d5..c0dcf2a2 100644
--- a/docs/en/reme_scene.md
+++ b/docs/en/reme_scene.md
@@ -54,20 +54,22 @@ session/
daily/
├── 2026-05-18.md
└── 2026-05-18/
- ├── 2026-05-18-close.md
- ├── glencore-q3.md
- ├── cobalt-policy.md
- ├── cathode-trend.md
+ ├── cobalt-supply-risk.md
+ ├── glencore-output-update.md
+ ├── drc-cobalt-policy.md
+ ├── high-nickel-cathode-trend.md
└── interests.yaml # generated after auto_dream
```
The corresponding flow is:
-- `auto_memory` saves the original conversation to `session/dialog/.jsonl`, then asks the agent to write
- important facts to `daily//.md`.
-- `resource_watch_loop` watches text-file changes under `resource/` and triggers `auto_resource_step` to write a
- same-named daily note.
-- `daily_create` maintains `daily/.md` as the index page for that day.
+- `auto_memory` saves a filtered source conversation record to `session/dialog/.jsonl`, then asks the agent to write
+ important facts to a topic-named `daily//.md`. The note keeps `session_id` and
+ `source_conversation` in frontmatter for stable lookup and provenance.
+- `resource_watch_loop` watches text-file changes under `resource/` and triggers `auto_resource_step` to write a daily note
+ with `source_resource`. The agent suggests a content-based filename, which the system sanitizes and de-duplicates; it is
+ not guaranteed to match the resource filename.
+- Auto Memory, Auto Resource, and Auto Dream refresh `daily/.md` after writing.
### Day 1 evening: Auto Dream writes to Digest
@@ -81,8 +83,8 @@ reme auto_dream date=2026-05-18
```text
dream_extract_step
- scan daily/2026-05-18.md and changed files under daily/2026-05-18/
- output units and topics
+ scan the daily window from 2026-05-17 through 2026-05-18 by default
+ output at most 5 units plus topics from changed files
dream_integrate_step
recall existing digest nodes with node_search for each unit
decide CREATE / CORROBORATE / REFINE / CORRECT
@@ -122,7 +124,7 @@ Changes to mining-rights policy in the DRC may affect KFM mine operations and sh
## Sources
-- [[daily/2026-05-18/2026-05-18-close.md]]
+The production decline and policy risk were recorded in [[daily/2026-05-18/cobalt-supply-risk.md]].
```
Note that wikilinks use literal path semantics. Prefer complete workspace-relative paths with the `.md` extension. ReMe
@@ -235,7 +237,7 @@ topics:
reason: The user repeatedly mentioned KFM and cobalt-price risk today
keywords: [cobalt, DRC, CMOC, KFM]
paths:
- - daily/2026-05-18/2026-05-18-close.md
+ - daily/2026-05-18/cobalt-supply-risk.md
```
Call:
@@ -321,7 +323,7 @@ The build stalls near the end. CPU usage is low, but memory keeps growing.
## Sources
-- [[daily/2026-03-10/build-oom-2026-03-10.md]]
+The failed attempts and successful memory adjustment were recorded in [[daily/2026-03-10/build-oom-2026-03-10.md]].
```
Example `digest/personal/code-style.md`:
@@ -374,7 +376,7 @@ and upgrading the minification plugin did not help last time.
- `digest/procedure/` stores both "how to do it" and "which paths failed," letting the agent reuse diagnostic experience.
- `digest/personal/` stores user preferences so the agent can follow the same engineering style across sessions.
-- The original conversation remains under `session/dialog/`; daily records stay traceable, and digest is only the
+- The source conversation record remains under `session/dialog/`; daily records stay traceable, and digest is only the
long-term distilled result.
## Scenario 3: A Personal Second Brain
@@ -423,7 +425,7 @@ At lunch on 2026-04-20, Alice recommended [[digest/wiki/deep-work.md]], a book a
## Sources
-- [[daily/2026-04-20/lunch-with-alice.md]]
+The recommendation was recorded in [[daily/2026-04-20/lunch-with-alice.md]].
```
### An associative recall
diff --git a/docs/figure/auto-dream-and-proactive.svg b/docs/figure/auto-dream-and-proactive.svg
index 0206f496..8ebe99cd 100644
--- a/docs/figure/auto-dream-and-proactive.svg
+++ b/docs/figure/auto-dream-and-proactive.svg
@@ -1,129 +1,117 @@
-