scriptoriumadmin/ReMe
1
0
Fork 0
mirror of https://github.com/agentscope-ai/ReMe.git synced 2026-09-06 08:16:00 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

docs: refresh ReMe guides, diagrams, and Studio documentation (#447)

Browse source 
* 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
This commit is contained in:
jinliyl 2026-08-12 10:59:03 +08:00 • committed by GitHub
parent 215c1f72f2
commit ab66f2bb56
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
53 changed files with 2864 additions and 2277 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

266
AGENTS.md
View file

@ -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=<name-or-path>` 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=<name> ...` 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/<version>/`. 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.

169
README.md
View file

@ -20,26 +20,28 @@
</p>
<p align="center">
<strong>An agent memory layer that turns conversations and resources into readable, editable, searchable Markdown memory.</strong><br>
<strong>A local-first, self-evolving personal knowledge base for AI agents.</strong><br>
</p>
> 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.
<p align="center">
<img src="docs/figure/design-philosophy.svg" alt="ReMe Design Philosophy" width="92%">
@ -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 <http://127.0.0.1:2333/> 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 <http://127.0.0.1:2333/>. Studio can
browse, edit, and search the workspace, chat with the read-only workspace agent, and inspect the digest wikilink graph.
Set `service.web_enabled=false` to disable it, or use `service.web_static_dir` / `REME_WEB_STATIC_DIR` to provide a
custom static build. The Job API remains available when no web build is found.
```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 <http://127.0.0.1:2333/> after starting the default HTTP service. Studio provides:
- **Files, Daily, and Knowledge views** for navigating the whole workspace or focusing on `daily/` and `digest/`.
- **Markdown tabs** with preview, split editing, optimistic save checks, and local download.
- **Memory Graph** for exploring indexed `personal`, `procedure`, and `wiki` nodes and opening their Markdown sources.
- **Read-only Agent chat** with streamed tool activity and usage; drag a workspace file into the composer to reference it.
- **Settings** for service/component status, redacted effective configuration, version information, and safe index rebuilding.
- English/Chinese language switching and light, dark, or system appearance.
For frontend development, run ReMe and Studio in separate terminals:
```bash
# Terminal 1, repository root
reme start
# Terminal 2
cd website
npm install
npm run dev
```
Then open <http://localhost:3000>. The development server uses `http://127.0.0.1:2333` by default; set
`NEXT_PUBLIC_REME_API_URL` to connect to another ReMe HTTP service. Static-build and frontend configuration instructions are
in the [ReMe Studio guide](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
<workspace_dir>/
├── 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/
│ │ └── <session_id>.jsonl
│ ├── agentscope/
│ │ └── <session_id>.jsonl # Source messages saved by auto_memory
│ └── claude_code/
│ └── <session_id>.jsonl # ReMe copy used by auto_memory_cc
├── mem_session/ # Generated agent-wrapper sessions/config, not user memory
│ ├── agentscope/
│ ├── claude_config/
│ └── codex/
├── resource/ # External raw materials
│ ├── <resource>.<ext> # Root-level files enter today's daily layer
│ └── YYYY-MM-DD/
│ └── <resource>.<ext>
├── daily/ # Lightly processed memory: daily facts, conversation summaries, resource readings
│ ├── YYYY-MM-DD.md
│ └── YYYY-MM-DD/
│ ├── <session_event>.md
│ ├── <resource_stem>.md
│ ├── <generated_name>.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/<date>/<session>.md` |
| [`auto_resource`](docs/en/auto_resource.md) | Resource watcher or `reme auto_resource` | Turns files under `resource/<date>/` into source-linked daily cards. | `daily/<date>/<resource-card>.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/<date>/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/<date>/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/<date>/<generated-name>.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/<date>/<resource-card>.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/<date>/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/<date>/interests.yaml` |
<table>
<tr>
@ -260,18 +321,44 @@ through search, wikilinks, or proactive topics.
</tr>
</table>
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. |
<p align="center"><b>Integration demos</b></p>
@ -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}
}
```

161
README_ZH.md
View file

@ -20,22 +20,23 @@
</p>
<p align="center">
<strong>一个将对话和资料转化为可读、可编辑、可检索 Markdown 记忆的 Agent 记忆层。</strong><br>
<strong>面向 AI Agent 的 local-first 自进化个人知识库。</strong><br>
</p>
> 历史版本：[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 是一个面向 **AI 智能体** 的 local-first 记忆层。它把对话和资料沉淀为文件化长期记忆，并持续完成索引、链接和整理，让后续
Agent 能够可靠召回。
🧠 ReMe 将对话和资料持续沉淀为可读、可编辑、可检索、相互链接的 Markdown 记忆。它可以与 QwenPaw、OpenClaw、Hermes 和 Claude
Code 等 Agent 协作，在持续整理知识的同时，始终把文件控制权留给用户。
## ✨ 核心创新
- **Memory as File**：以带 frontmatter 和 wikilink 的 Markdown 作为记忆节点，让用户和 Agent 都能直接读写。
- **自进化知识库**：通过 Auto Memory、Auto Resource 和 Auto Dream，把对话与资料逐步加工为长期记忆，并自动建立 wikilink 关系。
- **渐进式混合搜索**：融合 wikilink、BM25 和 embedding，支持从关键词匹配到语义召回、关系扩展的混合检索。
- **Agent 友好集成**：通过 SKILL.md + CLI 接入，方便不同 Agent 读写、维护与复用记忆。
- **Memory as File, File as Memory**：以带 frontmatter 和 wikilink 的 Markdown 作为记忆节点，用户和 Agent 都能直接查看、编辑、移动和备份。
- **自进化知识库**：Auto Memory、Auto Resource 和 Auto Dream 把对话与资料逐步加工为 daily 记忆和长期知识，Auto Link
再将关系与来源写回文件。
- **渐进式混合搜索**：融合 wikilink、BM25 和可选 embedding，从关键词匹配、语义召回到关系扩展，避免一次性将所有邻居全文塞入上下文。
- **Agent 友好集成**：可通过 SKILL.md + CLI 读写和维护同一个本地 workspace，也支持 HTTP、MCP 和 Python API 接入。
<p align="center">
<img src="docs/figure/design-philosophy.svg" alt="ReMe 设计理念" width="92%">
@ -52,11 +53,16 @@ Agent 能够可靠召回。
## 📰 新闻
- [2026.08] - 发布 [ReMe 博客](docs/zh/reme-blog.md)，系统介绍本地优先的记忆架构、自进化工作流、混合检索、
主动发现与评测结果。
- [2026.08] - 新增 [ReMe Studio](website/README_ZH.md)：用于浏览、编辑和搜索记忆文件，与只读 ReMe Agent
对话，查看 digest wikilink 图，并管理本地服务。
- [2026.08] - 基于 ReMe 的智能体工具使用
[经验驱动增强方法](benchmark/toolmemory/README_ZH.md)已发布，见
[arXiv:2608.03403](https://arxiv.org/abs/2608.03403)。
- [2026.07] - 新增可选 Cookbook 工作流：[每日论文](cookbook/daily_paper/README_ZH.md)用于论文发现与解析，
[Auto Fin](cookbook/auto-fin/README_ZH.md)用于研究最近 24 小时的主题相关财联社新闻，通过本地记忆搜索回顾历史材料并构建 wikilink。
[Auto Fin](cookbook/auto-fin/README_ZH.md)用于研究最近 24 小时的主题相关财联社新闻，通过本地记忆搜索回顾历史材料并构建
wikilink。
- [2026.07] -
我们的论文 [Remember Me, Refine Me: A Dynamic Procedural Memory Framework for Experience-Driven Agent Evolution](https://aclanthology.org/2026.findings-acl.829/)
已被 Findings of ACL 2026 接收。
@ -121,14 +127,44 @@ reme start service.port=8181
启动后可以检查服务状态；如果使用了自定义端口，请将下面 URL 中的 `2333` 替换为对应端口。
如果安装包中包含 Web 构建产物，HTTP 服务还会在 <http://127.0.0.1:2333/> 提供 ReMe Workspace。可以设置
`service.web_enabled=false` 关闭，或通过 `service.web_static_dir` / `REME_WEB_STATIC_DIR` 指定自定义静态目录。
如果安装包中包含 Web 构建产物，HTTP 服务还会在 <http://127.0.0.1:2333/> 提供 **ReMe Studio**，用于浏览、编辑和搜索
workspace，与只读 workspace agent 对话，以及查看 digest wikilink 图。可以设置
`service.web_enabled=false` 关闭，或通过 `service.web_static_dir` / `REME_WEB_STATIC_DIR` 指定自定义静态目录。找不到 Web
构建产物时，Job API 仍可正常使用。
```bash
reme version
reme health_check
reme help
curl -s http://127.0.0.1:2333/version -H 'Content-Type: application/json' -d '{}'
```
### 使用 ReMe Studio
启动默认 HTTP 服务后，在浏览器打开 <http://127.0.0.1:2333/>。Studio 提供：
- **文件、日记和知识库视图**：浏览整个 workspace，或聚焦 `daily/` 和 `digest/`。
- **Markdown 多标签页**：支持预览、分栏编辑、基于修改时间的冲突检查、保存和本地下载。
- **记忆图谱**：浏览已索引的 `personal`、`procedure` 和 `wiki` 节点，并打开对应 Markdown 源文件。
- **只读 Agent 对话**：流式查看工具调用和模型用量；可将 workspace 文件拖入输入框作为引用。
- **设置与服务管理**：查看服务/组件状态、脱敏后的生效配置和版本，并安全重建派生索引。
- 支持中英文切换，以及浅色、深色和跟随系统外观。
如需开发前端，在两个终端中分别启动 ReMe 和 Studio：
```bash
# 终端 1：仓库根目录
reme start
# 终端 2
cd website
npm install
npm run dev
```
然后打开 <http://localhost:3000>。开发服务默认连接 `http://127.0.0.1:2333`；如需连接其他 ReMe HTTP
服务，请设置 `NEXT_PUBLIC_REME_API_URL`。静态构建和前端配置说明见 [ReMe Studio 指南](website/README_ZH.md)。
### 5 分钟记忆 Demo
服务运行后，可以写入一个记忆节点，让 ReMe 索引并检索它：
@ -163,41 +199,63 @@ ReMe 会把 Agent 记忆保存为可读的 Markdown。
相关链接：[[digest/wiki/memory-as-file.md]]
```
## 📚 使用指南
下列 Markdown 文档覆盖主要使用流程，并以当前代码的运行时契约为准。
| 文档 | 主要内容 |
|------|----------|
| [快速开始](docs/zh/quick_start.md) | 安装 ReMe、启动服务、使用 Studio，并执行首次文件和记忆操作。 |
| [Memory as File](docs/zh/memory_as_file.md) | 理解 workspace 分层、frontmatter、wikilink、chunk 和文件事实来源模型。 |
| [Auto Memory](docs/zh/auto_memory.md) | 保留过滤后的对话来源记录，并提炼可复用的 daily 记忆卡片。 |
| [Auto Resource](docs/zh/auto_resource.md) | 导入支持的文本资料，转换为可追溯来源的 daily 卡片。 |
| [Auto Dream](docs/zh/auto_dream.md) 与 [Auto Link](docs/zh/auto_link.md) | 将 daily 记忆整理为持续演化的 digest 节点和可读 wikilink 关系。 |
| [记忆检索](docs/zh/memory_search.md) | 使用 BM25、可选向量、RRF 融合、行号范围召回和渐进式链接扩展。 |
| [Proactive](docs/zh/proactive.md) | 安全读取兴趣主题，并将其接入宿主 Agent 的决策流程。 |
| [Agent 接入场景](docs/zh/reme_scene.md) | 在 CLI/SKILL.md、HTTP、MCP 和嵌入式 Python 集成之间选择。 |
| [框架说明](docs/zh/framework.md) | 理解 Application、Job、Step、Component、service、配置和生命周期边界。 |
| [ReMe Studio](website/README_ZH.md) | 使用、配置、开发、测试和构建 Web 前端。 |
| [ReMe 博客](docs/zh/reme-blog.md) | 了解完整产品故事、设计动机、使用示例和评测摘要。 |
## 🧑‍🍳 Cookbooks
Cookbook 是由 ReMe jobs 和 steps 组装而成的可选端到端工作流。默认配置不会开启它们；启动 ReMe 时选择对应的 独立配置即可启用。后续新增的
Cookbook 是由 ReMe jobs 和 steps 组装而成的可选端到端工作流。默认配置不会开启它们；启动 ReMe 时选择对应的独立配置即可启用。后续新增的
cookbook 会继续在表格中按行追加。
| Cookbook | 能力 |
|-----------------------------------------------|-----------------------------------------------------------------------|
| [每日论文](cookbook/daily_paper/README_ZH.md) | 发现并排序论文，使用 Agent 解读 PDF，生成文件化论文笔记和五分钟简报。 |
| Cookbook | 能力 |
|-----------------------------------------------|--------------------------------------------------------------------------------|
| [每日论文](cookbook/daily_paper/README_ZH.md) | 发现并排序论文，使用 Agent 解读 PDF，生成文件化论文笔记和五分钟简报。 |
| [Auto Fin](cookbook/auto-fin/README_ZH.md) | 拉取主题相关财联社新闻，搜索 ReMe 历史材料并生成带 wikilink 的 Markdown 报告。 |
## 📁 记忆系统
> Memory as File, File as Memory.
ReMe 将 **记忆视为文件**，让原始对话和外部资料从 `session/`、`resource/` 渐进加工到 `daily/`，再沉淀为 `digest/`
中可长期复用的知识节点。
ReMe 将 **记忆视为文件**，让过滤后的对话来源记录和外部资料从 `session/`、`resource/` 渐进加工到 `daily/`，再沉淀为 `digest/`
中可长期复用的知识节点。默认 workspace 是当前目录下的 `.reme/`；可通过 `workspace_dir=...` 选择其他由用户控制的位置。
### 目录结构
```text
<workspace_dir>/
├── metadata/ # 系统索引、图谱、catalog 等持久状态
├── session/ # 原始对话和 Agent session
├── metadata/ # 可重建的索引、图谱、catalog 和缓存
├── session/ # 对话来源记录和 Agent session
│ ├── dialog/
│ │ └── <session_id>.jsonl
│ ├── agentscope/
│ │ └── <session_id>.jsonl # auto_memory 保存的来源消息
│ └── claude_code/
│ └── <session_id>.jsonl # auto_memory_cc 使用的 ReMe 副本
├── mem_session/ # Agent wrapper 生成的 session/配置，不是用户记忆
│ ├── agentscope/
│ ├── claude_config/
│ └── codex/
├── resource/ # 外部原始材料
│ ├── <resource>.<ext> # 根目录文件进入当天 daily 层
│ └── YYYY-MM-DD/
│ └── <resource>.<ext>
├── daily/ # 浅加工记忆：当天事实、对话摘要、资源解读
│ ├── YYYY-MM-DD.md
│ └── YYYY-MM-DD/
│ ├── <session_event>.md
│ ├── <resource_stem>.md
│ ├── <generated_name>.md # 按主题命名的对话或资源卡片
│ └── interests.yaml
└── digest/ # 长期记忆：个人事实、流程经验、知识节点
├── personal/
@ -214,20 +272,21 @@ ReMe 将 **记忆视为文件**，让原始对话和外部资料从 `session/`
## 🧭 记忆设计理念
> 捕获原始对话和资料，将其整理为长期偏好、可复用经验和有价值的知识，并让结果始终能被用户和 Agent 直接编辑。
> 捕获过滤后的对话来源记录和资料，将其整理为长期偏好、可复用经验和有价值的知识，并让结果始终能被用户和 Agent 直接编辑。
### 自动记忆流程
ReMe 遵循 capture → index → consolidate → recall 的循环。对话和资料先变成 daily 记忆卡片；后台任务保持文件可检索；
`auto_dream` 将稳定知识沉淀到 `digest/`；Agent 再通过搜索、wikilink 或 proactive topics 召回记忆。
`auto_dream` 将稳定知识沉淀到 `digest/`；Agent 再通过搜索、wikilink 或 proactive topics 召回记忆。文件是持久化的事实来源，
`metadata/` 中的索引、图谱、catalog 和缓存都可以由它们重建。
| 能力 | 入口 | 作用 | 输出 |
|---------------------------------------------|-------------------------------------------|--------------------------------------------------------------------------|-------------------------------------------------------|
| [`auto_memory`](docs/zh/auto_memory.md) | Agent hook 或 `reme auto_memory` | 提炼有长期价值的对话事实，同时保留原始 session。 | `session/dialog/*.jsonl`、`daily/<date>/<session>.md` |
| [`auto_resource`](docs/zh/auto_resource.md) | 资源监听或 `reme auto_resource` | 将 `resource/<date>/` 下的文件转为带来源链接的 daily 卡片。 | `daily/<date>/<resource-card>.md` |
| [`auto_index`](docs/zh/memory_search.md) | 后台监听或 `reme reindex` | 维护 chunks、BM25 索引、wikilink 图谱及可选的 embedding 索引。 | 可检索的 `daily/`、`digest/`、`resource/` 内容 |
| [`auto_dream`](docs/zh/auto_dream.md) | `dream_cron` 或 `reme auto_dream` | 将变化的 daily 卡片整理为长期 personal、procedure 和 wiki 记忆。 | `digest/**`、`daily/<date>/interests.yaml` |
| [`proactive`](docs/zh/proactive.md) | Agent 决定主动行动前调用 `reme proactive` | 读取 `auto_dream` 生成的 topics；是否以及如何提醒用户由宿主 Agent 决定。 | 来自 `daily/<date>/interests.yaml` 的结构化 topics |
| 能力 | 入口 | 作用 | 输出 |
|---------------------------------------------|-------------------------------------------|----------------------------------------------------------------------------------------------|--------------------------------------------------------------|
| [`auto_memory`](docs/zh/auto_memory.md) | Agent hook 或 `reme auto_memory` | 提炼有长期价值的对话事实，同时保留过滤后的对话来源记录。 | `session/dialog/*.jsonl`、`daily/<date>/<generated-name>.md` |
| [`auto_resource`](docs/zh/auto_resource.md) | 资源监听或 `reme auto_resource` | 将 `resource/` 下的文件转为带来源链接、按内容命名的 daily 卡片。 | `daily/<date>/<resource-card>.md` |
| [`auto_index`](docs/zh/memory_search.md) | 后台监听或 `reme reindex` | 实时索引 `daily/` 和 `digest/` 中的 Markdown；全量重建还会扫描 `resource/` 和 JSONL。 | 可检索的 chunks、BM25、wikilink 图谱和可选向量 |
| [`auto_dream`](docs/zh/auto_dream.md) | `dream_cron` 或 `reme auto_dream` | 默认从最近两天内变化的文件中最多提取 5 个可复用 unit，再创建、印证、补充或修正 digest 节点。 | `digest/**`、`daily/<date>/interests.yaml` |
| [`proactive`](docs/zh/proactive.md) | Agent 决定主动行动前调用 `reme proactive` | 读取 `auto_dream` 生成的 topics；是否以及如何提醒用户由宿主 Agent 决定。 | 来自 `daily/<date>/interests.yaml` 的结构化 topics |
<table>
<tr>
@ -248,17 +307,37 @@ ReMe 遵循 capture → index → consolidate → recall 的循环。对话和
</tr>
</table>
搜索会先返回最相关的 chunks、文件路径和行号范围，再以元数据形式列出数量受限的入链与出链邻居。Agent 只需在判断确实相关后再读取原文或继续遍历图谱。
启用 embedding 时，BM25 和向量排名通过 RRF 融合；默认未启用 embedding 时，则使用 BM25 + wikilink 扩展。
> [!IMPORTANT]
> `proactive` 只读取并暴露 Auto Dream 生成的兴趣主题，不会自行联网、发送通知或改写知识库；是否以及如何使用主题，由宿主 Agent
决定。
## 📊 性能表现
ReMe 通过 Agent 多轮搜索与读取的方式，评测多会话和超长上下文中的记忆能力。下表为仓库中已公开的参考实验结果；模型、prompt、数据集和评判细节见各评测文档。
| 基准 | 设置 | 样本量 | Agentic 得分 | 主要检验内容 |
|-----------------------------------------------------------------|-------------|------------------:|-------------:|--------------------------------|
| **[LongMemEval cleaned-s](benchmark/longmemeval/README_ZH.md)** | **整体** | **500 题** | **89.4%** | 跨会话检索、知识更新与时间推理 |
| [BEAM](benchmark/beam/README_ZH.md) | 100K 上下文 | 20 cases / 400 题 | 66.1% | 十类长上下文记忆任务 |
| [BEAM](benchmark/beam/README_ZH.md) | 1M 上下文 | 35 cases / 700 题 | 65.0% | 超长对话设置 |
在仓库的 [π-Bench 评测](benchmark/pibench/README_ZH.md)中，ReMe Agent 在 5 种用户角色上的平均 **PROC 得分为 0.580**
，比相同测试模型配置的 NanoBot 高 2.4%。PROC 用于评估隐藏意图完成、针对性澄清、跨会话偏好和规范复用、跨任务依赖推断以及欠规格请求推进等主动性能力。
## 🤝 Agent-friendly Integration
ReMe 既可以作为本地记忆服务，通过 CLI、HTTP API 或 MCP server 接入，也可以通过 Python API 嵌入宿主进程。不同 Agent
可以选择适合自身 runtime 的路径，并按需共享同一个本地 memory workspace。
ReMe 既可以作为本地记忆服务，通过 CLI、HTTP API 或 MCP server 接入，也可以通过 Python API 嵌入宿主进程。不同 Agent 可以选择适合自身
runtime 的路径，并按需共享同一个本地 memory workspace。默认 HTTP 服务还可以在同一地址提供 ReMe Studio。
| Agent | 推荐接入方式 | 接入后能力 |
|----------------------------------------|-----------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------|
| **QwenPaw** | 通过 Python API 在进程内嵌入 ReMe。 | 复用宿主应用的生命周期和模型配置，同时保持 memory 本地、文件化。 |
| **Claude Code** | 启动 streamable HTTP MCP service，并安装 [plugins/claude_code/reme](plugins/claude_code/reme)。 | MCP recall tools、`reme-memory` skill，以及自动记录会话的 Stop hook。 |
| **Hermes** | 启动 HTTP service，并安装 [plugins/hermes_agent](plugins/hermes_agent)。 | 在模型调用前自动召回相关记忆，并在每轮对话完成后异步调用 `auto_memory`。 |
| **Other CLI-capable agents (OpenClaw/Codex)** | 复制或安装 [skills/reme_memory/SKILL.md](skills/reme_memory/SKILL.md)。 | 通过 CLI 搜索、读取和写入记忆；自动记录需要宿主 Agent 显式接入会话生命周期。 |
| Agent | 推荐接入方式 | 接入后能力 |
|-----------------------------------------------|-------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------|
| **QwenPaw** | 通过 Python API 在进程内嵌入 ReMe。 | 复用宿主应用的生命周期和模型配置，同时保持 memory 本地、文件化。 |
| **Claude Code** | 启动 streamable HTTP MCP service，并安装 [plugins/claude_code/reme](plugins/claude_code/reme)。 | MCP recall tools、`reme-memory` skill，以及自动记录会话的 Stop hook。 |
| **Hermes** | 启动 HTTP service，并安装 [plugins/hermes_agent](plugins/hermes_agent)。 | 在模型调用前自动召回相关记忆，并在每轮对话完成后异步调用 `auto_memory`。 |
| **Other CLI-capable agents (OpenClaw/Codex)** | 复制或安装 [skills/reme_memory/SKILL.md](skills/reme_memory/SKILL.md)。 | 通过 CLI 搜索、读取和写入记忆；自动记录需要宿主 Agent 显式接入会话生命周期。 |
<p align="center"><b>集成演示</b></p>
@ -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}
}
```

44
cookbook/auto-fin/README.md
View file

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

48
cookbook/auto-fin/README_ZH.md
View file

@ -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)中列出的钉钉凭据。
## 验证

61
cookbook/daily_paper/README.md
View file

@ -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/
└── <arxiv-id>.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

73
cookbook/daily_paper/README_ZH.md
View file

@ -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/<date>/*.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/<date>/<中文标题>.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/
└── <arxiv-id>.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/<arxiv-id>`。两种 base URL 都会保留路径前缀，末尾 `/` 可有可无。不存在备用地址回退：客户端选定哪个 base URL，就只访问该地址。
`HF_MIRROR_URL` 必须提供当前代码使用的 `/papers/...`、`/api/daily_papers` 和 `/api/papers/...` 路径。`ARXIV_MIRROR_URL`
必须支持 `/pdf/<arxiv-id>`。两种 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；不会删除当日目录中已有的其他笔记。
- 多文件流程不是事务，也没有同一日期的全局运行锁。
## 测试

129
docs/en/auto_dream.md
View file

@ -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.
<p align="center">
<img src="../figure/auto-dream-and-proactive.svg" alt="ReMe Auto Dream and Proactive flow from daily to digest to proactive" width="92%">
</p>
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/<date>.md
daily/<date>/**/*.md
daily/2026-06-19.md
daily/2026-06-19/**/*.md
daily/2026-06-20.md
daily/2026-06-20/**/*.md
```
`daily/<date>/interests.yaml` is excluded from extraction input so topics from the previous run do not feed back into the
next extraction.
Every `daily/<date>/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/<date>/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/<date>/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/<date>.md`.
2. Scan `daily/<date>.md` and `daily/<date>/**/*.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/<date>.md` in the scan window.
2. Scan those day indexes and `daily/<date>/**/*.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/<date>/interests.yaml
daily/<previous-date>/interests.yaml
daily/<each of the previous topic_diversity_days dates>/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/<date>/interests.yaml` and `daily/<date>.md` to the catalog.
2. Also write the target `daily/<date>/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/<date>/...]]`. 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/<date>/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.

99
docs/en/auto_link.md
View file

@ -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/<bucket>/<slug>.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/<bucket>/<slug>.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.

51
docs/en/auto_memory.md
View file

@ -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.
<p align="center">
<img src="../figure/auto-memory-resource.svg" alt="ReMe Auto Memory and Auto Resource writing daily memory cards" width="92%">
@ -13,9 +14,9 @@ For the general file semantics of `daily/`, `session/`, frontmatter, and wikilin
```text
Conversation
├─ step 1: daily/YYYY-MM-DD/<session_id>.md # one card per conversation
├─ step 2: daily/YYYY-MM-DD.md # daily index linking the cards
└─ source: session/dialog/<session_id>.jsonl # original conversation
├─ step 1: daily/YYYY-MM-DD/<generated_name>.md # one topic-named card per session
├─ step 2: daily/YYYY-MM-DD.md # daily index linking the cards
└─ source: session/dialog/<session_id>.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 `<session_id>.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

46
docs/en/auto_resource.md
View file

@ -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.
<p align="center">
<img src="../figure/auto-memory-resource.svg" alt="ReMe Auto Memory and Auto Resource writing daily memory cards" width="92%">
@ -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_file>
resource/[YYYY-MM-DD/]<resource_file>
├─ step 1: daily/YYYY-MM-DD/<generated_name>.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/<resource_file>
## 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/<resource_stem>.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/<resource_stem>.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).

67
docs/en/contributing.md
View file

@ -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("<backend_name>")`. 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("<backend_name>")`. 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.

263
docs/en/framework.md
View file

@ -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
<workspace_dir>/
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=<name-or-path>` | 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=<name-or-path>` | 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 /<job.name>` returning `Response` JSON. |
| `StreamJob` | `POST /<job.name>` returning `text/event-stream`. |
| `enable_serve: false` | No endpoint is registered. |
| Job type | HTTP exposure |
|-------------------------------------------|---------------------------------------------------|
| Non-`StreamJob` with `enable_serve: true` | `POST /<job.name>` returning `Response` JSON. |
| `StreamJob` | `POST /<job.name>` 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 /<job.name>`
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<br/>index_update_loop<br/>resource_watch_loop<br/>digest_watch_loop"]
Jobs --> Base["base<br/>version / help / health_check<br/>search / node_search / traverse / reindex<br/>read / write / edit / delete / move / list / stat<br/>daily_list / daily_reindex / daily_write<br/>auto_memory / auto_resource / auto_dream / proactive"]
Jobs --> Cron["cron<br/>dream_cron<br/>optimize_index_cron"]
Jobs --> Stream["stream<br/>chat"]
Jobs --> Base["base<br/>version / help / health_check / status / app_config<br/>search / node_search / traverse / graph_snapshot / reindex<br/>read / load / read_image / write / save / edit / delete / move / list / stat / frontmatter_*<br/>daily_list / daily_reindex / daily_write<br/>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:

153
docs/en/memory_as_file.md
View file

@ -6,37 +6,39 @@ ReMe's core idea is **Memory as File, File as Memory**.
<img src="../figure/memory-as-file.svg" alt="ReMe Memory as File model" width="92%">
</p>
**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
<workspace_dir>/
├── 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/
│ │ └── <session_id>.jsonl # conversation messages saved by auto_memory
│ ├── agentscope/
│ │ └── <session_id>.jsonl
│ │ └── <session_id>.jsonl # source messages saved by auto_memory
│ └── claude_code/
│ └── <session_id>.jsonl
├── resource/ # raw input layer; original external material
│ └── <session_id>.jsonl # ReMe copy used by auto_memory_cc
├── mem_session/ # generated Agent wrapper sessions/config, not user memory
│ ├── agentscope/
│ ├── claude_config/
│ └── codex/
├── resource/ # source-record layer; original external material
│ ├── <resource>.<ext> # root-level input uses today's date
│ └── YYYY-MM-DD/
│ └── <resource>.<ext>
│ └── <resource>.<ext> # 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/
│ ├── <session_id>.md # daily note distilled from a conversation
│ ├── <resource_stem>.md # daily note distilled from a resource
│ ├── <generated_name>.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/<session_id>.jsonl
-> daily/YYYY-MM-DD/<session_id>.md
-> daily/YYYY-MM-DD/<generated_name>.md
-> digest/personal | digest/procedure | digest/wiki
external resource
-> resource/YYYY-MM-DD/<resource>.<ext>
-> daily/YYYY-MM-DD/<resource_stem>.md
-> resource/[YYYY-MM-DD/]<resource>.<ext>
-> daily/YYYY-MM-DD/<generated_name>.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.

86
docs/en/memory_search.md
View file

@ -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.
<p align="center">
<img src="../figure/auto-index-and-memory-search.svg" alt="ReMe Auto Index and Memory Search indexing, recall, fusion, and link expansion" width="92%">
@ -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`.

60
docs/en/proactive.md
View file

@ -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/<date>/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/<date>/interests.yaml`. |
| `topics` | Parsed topic list. |
| Field | Description |
|-----------|------------------------------------------------------|
| `date` | The date actually read. |
| `path` | `daily/<date>/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.

39
docs/en/quick_start.md
View file

@ -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 <http://127.0.0.1:2333/> 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),

30
docs/en/reme-blog.md
View file

@ -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
<img src="../figure/reme-blog/reme-blog-memory-index.svg" alt="ReMe Memory Index build process" width="100%">
</p>
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 |
|-------|-------------------------|--------------------------------|

34
docs/en/reme_scene.md
View file

@ -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/<session_id>.jsonl`, then asks the agent to write
important facts to `daily/<date>/<session_id>.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/<date>.md` as the index page for that day.
- `auto_memory` saves a filtered source conversation record to `session/dialog/<session_id>.jsonl`, then asks the agent to write
important facts to a topic-named `daily/<date>/<generated_name>.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/<date>.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

226
docs/figure/auto-dream-and-proactive.svg
View file

@ -1,129 +1,117 @@
<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="640" viewBox="0 0 1200 640" role="img" aria-labelledby="title desc">
<title id="title">ReMe auto dream and proactive flow</title>
<desc id="desc">A left-to-right flow from changed daily notes to digest integration, interest topic writing, catalog checkpointing, and proactive reads.</desc>
<defs>
<style>
.bg { fill: #fffdf8; }
.title { font: 700 30px "Comic Sans MS", "Bradley Hand", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #1f2430; }
.subtitle { font: 14px "Comic Sans MS", "Bradley Hand", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #556276; }
.step-num { font: 700 12px "Comic Sans MS", "Bradley Hand", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #ffffff; }
.step-title { font: 700 18px "Comic Sans MS", "Bradley Hand", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #1f2430; }
.step-subtitle { font: 13px "Comic Sans MS", "Bradley Hand", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #556276; }
.chip-title { font: 700 13px "Comic Sans MS", "Bradley Hand", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #1f2430; }
.chip-text { font: 12px "Comic Sans MS", "Bradley Hand", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #5e6a7c; }
.note { font: 12px "Comic Sans MS", "Bradley Hand", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #4f5c6f; }
.panel { fill: #ffffff; stroke: #1f2430; stroke-width: 2.2; rx: 18; ry: 18; stroke-linecap: round; stroke-linejoin: round; }
.chip { fill: #f8fbff; stroke: #1f2430; stroke-width: 1.6; rx: 11; ry: 11; stroke-linecap: round; stroke-linejoin: round; stroke-dasharray: 6 5; }
.badge { fill: #44546a; }
.arrow { stroke: #7f8b9d; stroke-width: 1.45; fill: none; stroke-linecap: round; stroke-linejoin: round; marker-end: url(#arrow); }
.soft-arrow { stroke: #a3adbd; stroke-width: 1.25; stroke-dasharray: 6 6; fill: none; stroke-linecap: round; stroke-linejoin: round; marker-end: url(#arrow-soft); }
.line { stroke: #a3adbd; stroke-width: 1.25; stroke-linecap: round; }
</style>
<marker id="arrow" markerWidth="6" markerHeight="6" refX="5" refY="2" orient="auto" markerUnits="strokeWidth">
<path d="M0,0 L0,4 L5,2 z" fill="#7f8b9d"/>
</marker>
<marker id="arrow-soft" markerWidth="6" markerHeight="6" refX="5" refY="2" orient="auto" markerUnits="strokeWidth">
<path d="M0,0 L0,4 L5,2 z" fill="#a3adbd"/>
</marker>
</defs>
<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="640" viewBox="0 0 1200 640" role="img"
aria-labelledby="title desc">
<title id="title">ReMe auto dream and proactive flow</title>
<desc id="desc">A left-to-right flow from a recent changed-daily window to digest integration, interest topic
writing, catalog checkpointing, and proactive reads.
</desc>
<defs>
<style>.bg { fill: #fffdf8; } .title { font: 700 30px "Comic Sans MS", "Bradley Hand", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #1f2430; } .subtitle { font: 14px "Comic Sans MS", "Bradley Hand", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #556276; } .step-num { font: 700 12px "Comic Sans MS", "Bradley Hand", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #ffffff; } .step-title { font: 700 18px "Comic Sans MS", "Bradley Hand", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #1f2430; } .step-subtitle { font: 13px "Comic Sans MS", "Bradley Hand", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #556276; } .chip-title { font: 700 13px "Comic Sans MS", "Bradley Hand", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #1f2430; } .chip-text { font: 12px "Comic Sans MS", "Bradley Hand", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #5e6a7c; } .note { font: 12px "Comic Sans MS", "Bradley Hand", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #4f5c6f; } .panel { fill: #ffffff; stroke: #1f2430; stroke-width: 2.2; rx: 18; ry: 18; stroke-linecap: round; stroke-linejoin: round; } .chip { fill: #f8fbff; stroke: #1f2430; stroke-width: 1.6; rx: 11; ry: 11; stroke-linecap: round; stroke-linejoin: round; stroke-dasharray: 6 5; } .badge { fill: #44546a; } .arrow { stroke: #7f8b9d; stroke-width: 1.45; fill: none; stroke-linecap: round; stroke-linejoin: round; marker-end: url(#arrow); } .soft-arrow { stroke: #a3adbd; stroke-width: 1.25; stroke-dasharray: 6 6; fill: none; stroke-linecap: round; stroke-linejoin: round; marker-end: url(#arrow-soft); } .line { stroke: #a3adbd; stroke-width: 1.25; stroke-linecap: round; }</style>
<marker id="arrow" markerWidth="6" markerHeight="6" refX="5" refY="2" orient="auto" markerUnits="strokeWidth">
<path d="M0,0 L0,4 L5,2 z" fill="#7f8b9d"/>
</marker>
<marker id="arrow-soft" markerWidth="6" markerHeight="6" refX="5" refY="2" orient="auto"
markerUnits="strokeWidth">
<path d="M0,0 L0,4 L5,2 z" fill="#a3adbd"/>
</marker>
</defs>
<rect class="bg" x="0" y="0" width="1200" height="640"/>
<text class="title" x="600" y="54" text-anchor="middle">Auto Dream and Proactive</text>
<text class="subtitle" x="600" y="80" text-anchor="middle">Scan changed daily memory, integrate reusable units into digest, then expose proactive topics.</text>
<rect class="bg" x="0" y="0" width="1200" height="640"/>
<text class="title" x="600" y="54" text-anchor="middle">Auto Dream and Proactive</text>
<text class="subtitle" x="600" y="80" text-anchor="middle">Scan a recent daily window, integrate a compact set of reusable units, then expose proactive topics.</text>
<rect class="panel" x="38" y="132" width="196" height="300"/>
<circle class="badge" cx="72" cy="170" r="15"/>
<text class="step-num" x="72" y="174" text-anchor="middle">1</text>
<text class="step-title" x="100" y="176">Extract</text>
<text class="step-subtitle" x="66" y="206">dream_extract_step</text>
<rect class="chip" x="66" y="232" width="140" height="44"/>
<text class="chip-title" x="136" y="251" text-anchor="middle">refresh index</text>
<text class="chip-text" x="136" y="269" text-anchor="middle">daily/&lt;date&gt;.md</text>
<rect class="chip" x="66" y="296" width="140" height="44"/>
<text class="chip-title" x="136" y="315" text-anchor="middle">compare catalog</text>
<text class="chip-text" x="136" y="333" text-anchor="middle">changed daily</text>
<rect class="chip" x="66" y="360" width="140" height="44"/>
<text class="chip-title" x="136" y="379" text-anchor="middle">LLM extract</text>
<text class="chip-text" x="136" y="397" text-anchor="middle">units + topics</text>
<rect class="panel" x="38" y="132" width="196" height="300"/>
<circle class="badge" cx="72" cy="170" r="15"/>
<text class="step-num" x="72" y="174" text-anchor="middle">1</text>
<text class="step-title" x="100" y="176">Extract</text>
<text class="step-subtitle" x="66" y="206">dream_extract_step</text>
<rect class="chip" x="66" y="232" width="140" height="44"/>
<text class="chip-title" x="136" y="251" text-anchor="middle">refresh index</text>
<text class="chip-text" x="136" y="269" text-anchor="middle">recent 2 days</text>
<rect class="chip" x="66" y="296" width="140" height="44"/>
<text class="chip-title" x="136" y="315" text-anchor="middle">compare catalog</text>
<text class="chip-text" x="136" y="333" text-anchor="middle">changed daily</text>
<rect class="chip" x="66" y="360" width="140" height="44"/>
<text class="chip-title" x="136" y="379" text-anchor="middle">LLM extract</text>
<text class="chip-text" x="136" y="397" text-anchor="middle">≤ 5 units + topics</text>
<rect class="panel" x="270" y="132" width="196" height="300"/>
<circle class="badge" cx="304" cy="170" r="15"/>
<text class="step-num" x="304" y="174" text-anchor="middle">2</text>
<text class="step-title" x="332" y="176">Integrate</text>
<text class="step-subtitle" x="298" y="206">dream_integrate_step</text>
<rect class="chip" x="298" y="232" width="140" height="44"/>
<text class="chip-title" x="368" y="251" text-anchor="middle">node_search</text>
<text class="chip-text" x="368" y="269" text-anchor="middle">recall digest</text>
<rect class="chip" x="298" y="296" width="140" height="44"/>
<text class="chip-title" x="368" y="315" text-anchor="middle">auto link</text>
<text class="chip-text" x="368" y="333" text-anchor="middle">dedup + links</text>
<rect class="chip" x="298" y="360" width="140" height="44"/>
<text class="chip-title" x="368" y="379" text-anchor="middle">write digest</text>
<text class="chip-text" x="368" y="397" text-anchor="middle">create / update</text>
<rect class="panel" x="270" y="132" width="196" height="300"/>
<circle class="badge" cx="304" cy="170" r="15"/>
<text class="step-num" x="304" y="174" text-anchor="middle">2</text>
<text class="step-title" x="332" y="176">Integrate</text>
<text class="step-subtitle" x="298" y="206">dream_integrate_step</text>
<rect class="chip" x="298" y="232" width="140" height="44"/>
<text class="chip-title" x="368" y="251" text-anchor="middle">node_search</text>
<text class="chip-text" x="368" y="269" text-anchor="middle">recall digest</text>
<rect class="chip" x="298" y="296" width="140" height="44"/>
<text class="chip-title" x="368" y="315" text-anchor="middle">auto link</text>
<text class="chip-text" x="368" y="333" text-anchor="middle">dedup + links</text>
<rect class="chip" x="298" y="360" width="140" height="44"/>
<text class="chip-title" x="368" y="379" text-anchor="middle">write digest</text>
<text class="chip-text" x="368" y="397" text-anchor="middle">create / update</text>
<rect class="panel" x="502" y="132" width="196" height="300"/>
<circle class="badge" cx="536" cy="170" r="15"/>
<text class="step-num" x="536" y="174" text-anchor="middle">3</text>
<text class="step-title" x="564" y="176">Topics</text>
<text class="step-subtitle" x="530" y="206">dream_topics_step</text>
<rect class="chip" x="530" y="232" width="140" height="44"/>
<text class="chip-title" x="600" y="251" text-anchor="middle">merge topics</text>
<text class="chip-text" x="600" y="269" text-anchor="middle">same day kept</text>
<rect class="chip" x="530" y="296" width="140" height="44"/>
<text class="chip-title" x="600" y="315" text-anchor="middle">avoid repeats</text>
<text class="chip-text" x="600" y="333" text-anchor="middle">last 7 days</text>
<rect class="chip" x="530" y="360" width="140" height="44"/>
<text class="chip-title" x="600" y="379" text-anchor="middle">write YAML</text>
<text class="chip-text" x="600" y="397" text-anchor="middle">interests.yaml</text>
<rect class="panel" x="502" y="132" width="196" height="300"/>
<circle class="badge" cx="536" cy="170" r="15"/>
<text class="step-num" x="536" y="174" text-anchor="middle">3</text>
<text class="step-title" x="564" y="176">Topics</text>
<text class="step-subtitle" x="530" y="206">dream_topics_step</text>
<rect class="chip" x="530" y="232" width="140" height="44"/>
<text class="chip-title" x="600" y="251" text-anchor="middle">merge topics</text>
<text class="chip-text" x="600" y="269" text-anchor="middle">same day kept</text>
<rect class="chip" x="530" y="296" width="140" height="44"/>
<text class="chip-title" x="600" y="315" text-anchor="middle">avoid repeats</text>
<text class="chip-text" x="600" y="333" text-anchor="middle">last 7 days</text>
<rect class="chip" x="530" y="360" width="140" height="44"/>
<text class="chip-title" x="600" y="379" text-anchor="middle">write YAML</text>
<text class="chip-text" x="600" y="397" text-anchor="middle">interests.yaml</text>
<rect class="panel" x="734" y="132" width="196" height="300"/>
<circle class="badge" cx="768" cy="170" r="15"/>
<text class="step-num" x="768" y="174" text-anchor="middle">4</text>
<text class="step-title" x="796" y="176">Finish</text>
<text class="step-subtitle" x="762" y="206">dream_finish_step</text>
<rect class="chip" x="762" y="232" width="140" height="44"/>
<text class="chip-title" x="832" y="251" text-anchor="middle">checkpoint</text>
<text class="chip-text" x="832" y="269" text-anchor="middle">skip failures</text>
<rect class="chip" x="762" y="296" width="140" height="44"/>
<text class="chip-title" x="832" y="315" text-anchor="middle">persist catalog</text>
<text class="chip-text" x="832" y="333" text-anchor="middle">file_catalog</text>
<rect class="chip" x="762" y="360" width="140" height="44"/>
<text class="chip-title" x="832" y="379" text-anchor="middle">return summary</text>
<text class="chip-text" x="832" y="397" text-anchor="middle">counts + errors</text>
<rect class="panel" x="734" y="132" width="196" height="300"/>
<circle class="badge" cx="768" cy="170" r="15"/>
<text class="step-num" x="768" y="174" text-anchor="middle">4</text>
<text class="step-title" x="796" y="176">Finish</text>
<text class="step-subtitle" x="762" y="206">dream_finish_step</text>
<rect class="chip" x="762" y="232" width="140" height="44"/>
<text class="chip-title" x="832" y="251" text-anchor="middle">checkpoint</text>
<text class="chip-text" x="832" y="269" text-anchor="middle">skip failures</text>
<rect class="chip" x="762" y="296" width="140" height="44"/>
<text class="chip-title" x="832" y="315" text-anchor="middle">persist catalog</text>
<text class="chip-text" x="832" y="333" text-anchor="middle">file_catalog</text>
<rect class="chip" x="762" y="360" width="140" height="44"/>
<text class="chip-title" x="832" y="379" text-anchor="middle">return summary</text>
<text class="chip-text" x="832" y="397" text-anchor="middle">counts + errors</text>
<rect class="panel" x="966" y="132" width="196" height="300"/>
<circle class="badge" cx="1000" cy="170" r="15"/>
<text class="step-num" x="1000" y="174" text-anchor="middle">5</text>
<text class="step-title" x="1028" y="176">Proactive</text>
<text class="step-subtitle" x="994" y="206">proactive_step</text>
<rect class="chip" x="994" y="232" width="140" height="44"/>
<text class="chip-title" x="1064" y="251" text-anchor="middle">read YAML</text>
<text class="chip-text" x="1064" y="269" text-anchor="middle">interests.yaml</text>
<rect class="chip" x="994" y="296" width="140" height="44"/>
<text class="chip-title" x="1064" y="315" text-anchor="middle">return topics</text>
<text class="chip-text" x="1064" y="333" text-anchor="middle">metadata</text>
<rect class="chip" x="994" y="360" width="140" height="44"/>
<text class="chip-title" x="1064" y="379" text-anchor="middle">agent decides</text>
<text class="chip-text" x="1064" y="397" text-anchor="middle">whether to notify</text>
<rect class="panel" x="966" y="132" width="196" height="300"/>
<circle class="badge" cx="1000" cy="170" r="15"/>
<text class="step-num" x="1000" y="174" text-anchor="middle">5</text>
<text class="step-title" x="1028" y="176">Proactive</text>
<text class="step-subtitle" x="994" y="206">proactive_step</text>
<rect class="chip" x="994" y="232" width="140" height="44"/>
<text class="chip-title" x="1064" y="251" text-anchor="middle">read YAML</text>
<text class="chip-text" x="1064" y="269" text-anchor="middle">interests.yaml</text>
<rect class="chip" x="994" y="296" width="140" height="44"/>
<text class="chip-title" x="1064" y="315" text-anchor="middle">return topics</text>
<text class="chip-text" x="1064" y="333" text-anchor="middle">metadata</text>
<rect class="chip" x="994" y="360" width="140" height="44"/>
<text class="chip-title" x="1064" y="379" text-anchor="middle">agent decides</text>
<text class="chip-text" x="1064" y="397" text-anchor="middle">whether to notify</text>
<path class="arrow" d="M234 282 H270"/>
<path class="arrow" d="M466 282 H502"/>
<path class="arrow" d="M698 282 H734"/>
<path class="arrow" d="M930 282 H966"/>
<path class="arrow" d="M234 282 H270"/>
<path class="arrow" d="M466 282 H502"/>
<path class="arrow" d="M698 282 H734"/>
<path class="arrow" d="M930 282 H966"/>
<rect class="panel" x="80" y="502" width="1040" height="82"/>
<text class="note" x="126" y="532">Inputs</text>
<text class="chip-text" x="126" y="554">daily/&lt;date&gt;.md and daily/&lt;date&gt;/**/*.md</text>
<line class="line" x1="358" y1="518" x2="358" y2="566"/>
<text class="chip-title" x="402" y="532">Long-term memory</text>
<text class="chip-text" x="402" y="554">digest/procedure, digest/personal, digest/wiki</text>
<line class="line" x1="704" y1="518" x2="704" y2="566"/>
<text class="chip-title" x="748" y="532">Proactive material</text>
<text class="chip-text" x="748" y="554">daily/&lt;date&gt;/interests.yaml</text>
<line class="line" x1="942" y1="518" x2="942" y2="566"/>
<text class="chip-title" x="972" y="532">Boundary</text>
<text class="chip-text" x="972" y="554">Read only; caller decides</text>
<rect class="panel" x="80" y="502" width="1040" height="82"/>
<text class="note" x="126" y="532">Inputs</text>
<text class="chip-text" x="126" y="554">recent scan_days; changed files</text>
<line class="line" x1="358" y1="518" x2="358" y2="566"/>
<text class="chip-title" x="402" y="532">Long-term memory</text>
<text class="chip-text" x="402" y="554">digest/{procedure, personal, wiki}</text>
<line class="line" x1="704" y1="518" x2="704" y2="566"/>
<text class="chip-title" x="748" y="532">Proactive material</text>
<text class="chip-text" x="748" y="554">daily/&lt;date&gt;/interests.yaml</text>
<line class="line" x1="942" y1="518" x2="942" y2="566"/>
<text class="chip-title" x="972" y="532">Boundary</text>
<text class="chip-text" x="972" y="554" style="font-size:11px">Read-only; caller decides</text>
<path class="soft-arrow" d="M1064 432 C1064 476 600 472 600 432"/>
<text class="note" x="834" y="474" text-anchor="middle">proactive reads interests.yaml after auto_dream writes it</text>
<path class="soft-arrow" d="M1064 432 C1064 476 600 472 600 432"/>
<text class="note" x="834" y="474" text-anchor="middle">proactive reads interests.yaml after auto_dream writes it</text>
</svg>

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 9 KiB

After

Width:  |  Height:  |  Size: 9.2 KiB

166
docs/figure/auto-index-and-memory-search.svg
View file

@ -1,98 +1,86 @@
<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="640" viewBox="0 0 1200 640" role="img" aria-labelledby="title desc">
<title id="title">ReMe auto index and memory search flow</title>
<desc id="desc">A concise left-to-right flow from automatic workspace indexing to memory search and progressive link expansion.</desc>
<defs>
<style>
.bg { fill: #fffdf8; }
.title { font: 700 30px "Comic Sans MS", "Bradley Hand", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #1f2430; }
.subtitle { font: 14px "Comic Sans MS", "Bradley Hand", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #556276; }
.step-num { font: 700 12px "Comic Sans MS", "Bradley Hand", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #ffffff; }
.step-title { font: 700 18px "Comic Sans MS", "Bradley Hand", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #1f2430; }
.step-subtitle { font: 13px "Comic Sans MS", "Bradley Hand", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #556276; }
.chip-title { font: 700 13px "Comic Sans MS", "Bradley Hand", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #1f2430; }
.chip-text { font: 12px "Comic Sans MS", "Bradley Hand", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #5e6a7c; }
.note { font: 12px "Comic Sans MS", "Bradley Hand", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #4f5c6f; }
.panel { fill: #ffffff; stroke: #1f2430; stroke-width: 2.2; rx: 18; ry: 18; stroke-linecap: round; stroke-linejoin: round; }
.chip { fill: #f8fbff; stroke: #1f2430; stroke-width: 1.6; rx: 11; ry: 11; stroke-linecap: round; stroke-linejoin: round; stroke-dasharray: 6 5; }
.badge { fill: #44546a; }
.arrow { stroke: #7f8b9d; stroke-width: 1.45; fill: none; stroke-linecap: round; stroke-linejoin: round; marker-end: url(#arrow); }
.soft-arrow { stroke: #a3adbd; stroke-width: 1.25; stroke-dasharray: 6 6; fill: none; stroke-linecap: round; stroke-linejoin: round; marker-end: url(#arrow-soft); }
.line { stroke: #a3adbd; stroke-width: 1.25; stroke-linecap: round; }
</style>
<marker id="arrow" markerWidth="6" markerHeight="6" refX="5" refY="2" orient="auto" markerUnits="strokeWidth">
<path d="M0,0 L0,4 L5,2 z" fill="#7f8b9d"/>
</marker>
<marker id="arrow-soft" markerWidth="6" markerHeight="6" refX="5" refY="2" orient="auto" markerUnits="strokeWidth">
<path d="M0,0 L0,4 L5,2 z" fill="#a3adbd"/>
</marker>
</defs>
<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="640" viewBox="0 0 1200 640" role="img"
aria-labelledby="title desc">
<title id="title">ReMe auto index and memory search flow</title>
<desc id="desc">A concise left-to-right flow from live daily and digest Markdown indexing to memory search and
progressive link expansion.
</desc>
<defs>
<style>.bg { fill: #fffdf8; } .title { font: 700 30px "Comic Sans MS", "Bradley Hand", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #1f2430; } .subtitle { font: 14px "Comic Sans MS", "Bradley Hand", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #556276; } .step-num { font: 700 12px "Comic Sans MS", "Bradley Hand", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #ffffff; } .step-title { font: 700 18px "Comic Sans MS", "Bradley Hand", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #1f2430; } .step-subtitle { font: 13px "Comic Sans MS", "Bradley Hand", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #556276; } .chip-title { font: 700 13px "Comic Sans MS", "Bradley Hand", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #1f2430; } .chip-text { font: 12px "Comic Sans MS", "Bradley Hand", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #5e6a7c; } .note { font: 12px "Comic Sans MS", "Bradley Hand", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #4f5c6f; } .panel { fill: #ffffff; stroke: #1f2430; stroke-width: 2.2; rx: 18; ry: 18; stroke-linecap: round; stroke-linejoin: round; } .chip { fill: #f8fbff; stroke: #1f2430; stroke-width: 1.6; rx: 11; ry: 11; stroke-linecap: round; stroke-linejoin: round; stroke-dasharray: 6 5; } .badge { fill: #44546a; } .arrow { stroke: #7f8b9d; stroke-width: 1.45; fill: none; stroke-linecap: round; stroke-linejoin: round; marker-end: url(#arrow); } .soft-arrow { stroke: #a3adbd; stroke-width: 1.25; stroke-dasharray: 6 6; fill: none; stroke-linecap: round; stroke-linejoin: round; marker-end: url(#arrow-soft); } .line { stroke: #a3adbd; stroke-width: 1.25; stroke-linecap: round; }</style>
<marker id="arrow" markerWidth="6" markerHeight="6" refX="5" refY="2" orient="auto" markerUnits="strokeWidth">
<path d="M0,0 L0,4 L5,2 z" fill="#7f8b9d"/>
</marker>
<marker id="arrow-soft" markerWidth="6" markerHeight="6" refX="5" refY="2" orient="auto"
markerUnits="strokeWidth">
<path d="M0,0 L0,4 L5,2 z" fill="#a3adbd"/>
</marker>
</defs>
<rect class="bg" x="0" y="0" width="1200" height="640"/>
<text class="title" x="600" y="54" text-anchor="middle">Auto Index and Memory Search</text>
<text class="subtitle" x="600" y="80" text-anchor="middle">Keep workspace indexes fresh, recall relevant chunks, then expand nearby wikilink context.</text>
<rect class="bg" x="0" y="0" width="1200" height="640"/>
<text class="title" x="600" y="54" text-anchor="middle">Auto Index and Memory Search</text>
<text class="subtitle" x="600" y="80" text-anchor="middle">Keep workspace indexes fresh, recall relevant chunks, then expand nearby wikilink context.</text>
<rect class="panel" x="64" y="150" width="232" height="260"/>
<circle class="badge" cx="100" cy="188" r="15"/>
<text class="step-num" x="100" y="192" text-anchor="middle">1</text>
<text class="step-title" x="128" y="194">Watch memory</text>
<text class="step-subtitle" x="92" y="224">index_update_loop</text>
<rect class="chip" x="92" y="250" width="176" height="44"/>
<text class="chip-title" x="180" y="269" text-anchor="middle">daily / digest / resource</text>
<text class="chip-text" x="180" y="287" text-anchor="middle">md and jsonl files</text>
<rect class="chip" x="92" y="314" width="176" height="44"/>
<text class="chip-title" x="180" y="333" text-anchor="middle">init + watch changes</text>
<text class="chip-text" x="180" y="351" text-anchor="middle">added / modified / deleted</text>
<rect class="panel" x="64" y="150" width="232" height="260"/>
<circle class="badge" cx="100" cy="188" r="15"/>
<text class="step-num" x="100" y="192" text-anchor="middle">1</text>
<text class="step-title" x="128" y="194">Watch memory</text>
<text class="step-subtitle" x="92" y="224">index_update_loop</text>
<rect class="chip" x="92" y="250" width="176" height="44"/>
<text class="chip-title" x="180" y="269" text-anchor="middle">daily / digest</text>
<text class="chip-text" x="180" y="287" text-anchor="middle">Markdown live watch</text>
<rect class="chip" x="92" y="314" width="176" height="44"/>
<text class="chip-title" x="180" y="333" text-anchor="middle">init + watch changes</text>
<text class="chip-text" x="180" y="351" text-anchor="middle">added / modified / deleted</text>
<rect class="panel" x="348" y="150" width="232" height="260"/>
<circle class="badge" cx="384" cy="188" r="15"/>
<text class="step-num" x="384" y="192" text-anchor="middle">2</text>
<text class="step-title" x="412" y="194">Build index</text>
<text class="step-subtitle" x="376" y="224">update_index_step</text>
<rect class="chip" x="376" y="250" width="176" height="44"/>
<text class="chip-title" x="464" y="269" text-anchor="middle">chunk file</text>
<text class="chip-text" x="464" y="287" text-anchor="middle">FileNode + FileChunk[]</text>
<rect class="chip" x="376" y="314" width="176" height="44"/>
<text class="chip-title" x="464" y="333" text-anchor="middle">store structures</text>
<text class="chip-text" x="464" y="351" text-anchor="middle">BM25 + graph + chunks</text>
<rect class="panel" x="348" y="150" width="232" height="260"/>
<circle class="badge" cx="384" cy="188" r="15"/>
<text class="step-num" x="384" y="192" text-anchor="middle">2</text>
<text class="step-title" x="412" y="194">Build index</text>
<text class="step-subtitle" x="376" y="224">update_index_step</text>
<rect class="chip" x="376" y="250" width="176" height="44"/>
<text class="chip-title" x="464" y="269" text-anchor="middle">chunk file</text>
<text class="chip-text" x="464" y="287" text-anchor="middle">FileNode + FileChunk[]</text>
<rect class="chip" x="376" y="314" width="176" height="44"/>
<text class="chip-title" x="464" y="333" text-anchor="middle">store structures</text>
<text class="chip-text" x="464" y="351" text-anchor="middle">BM25 + graph + chunks</text>
<rect class="panel" x="632" y="150" width="232" height="260"/>
<circle class="badge" cx="668" cy="188" r="15"/>
<text class="step-num" x="668" y="192" text-anchor="middle">3</text>
<text class="step-title" x="696" y="194">Recall chunks</text>
<text class="step-subtitle" x="660" y="224">search_step</text>
<rect class="chip" x="660" y="250" width="176" height="44"/>
<text class="chip-title" x="748" y="269" text-anchor="middle">BM25 search</text>
<text class="chip-text" x="748" y="287" text-anchor="middle">keyword-ranked chunks</text>
<rect class="chip" x="660" y="314" width="176" height="44"/>
<text class="chip-title" x="748" y="333" text-anchor="middle">optional vector search</text>
<text class="chip-text" x="748" y="351" text-anchor="middle">RRF fusion when enabled</text>
<rect class="panel" x="632" y="150" width="232" height="260"/>
<circle class="badge" cx="668" cy="188" r="15"/>
<text class="step-num" x="668" y="192" text-anchor="middle">3</text>
<text class="step-title" x="696" y="194">Recall chunks</text>
<text class="step-subtitle" x="660" y="224">search_step</text>
<rect class="chip" x="660" y="250" width="176" height="44"/>
<text class="chip-title" x="748" y="269" text-anchor="middle">BM25 search</text>
<text class="chip-text" x="748" y="287" text-anchor="middle">keyword-ranked chunks</text>
<rect class="chip" x="660" y="314" width="176" height="44"/>
<text class="chip-title" x="748" y="333" text-anchor="middle">optional vector search</text>
<text class="chip-text" x="748" y="351" text-anchor="middle">RRF fusion when enabled</text>
<rect class="panel" x="916" y="150" width="220" height="260"/>
<circle class="badge" cx="952" cy="188" r="15"/>
<text class="step-num" x="952" y="192" text-anchor="middle">4</text>
<text class="step-title" x="980" y="194">Expand context</text>
<text class="step-subtitle" x="944" y="224">expand_links</text>
<rect class="chip" x="944" y="250" width="164" height="44"/>
<text class="chip-title" x="1026" y="269" text-anchor="middle">top chunks</text>
<text class="chip-text" x="1026" y="287" text-anchor="middle">path + line range</text>
<rect class="chip" x="944" y="314" width="164" height="44"/>
<text class="chip-title" x="1026" y="333" text-anchor="middle">outlinks + inlinks</text>
<text class="chip-text" x="1026" y="351" text-anchor="middle">name, description, via</text>
<rect class="panel" x="916" y="150" width="220" height="260"/>
<circle class="badge" cx="952" cy="188" r="15"/>
<text class="step-num" x="952" y="192" text-anchor="middle">4</text>
<text class="step-title" x="980" y="194">Expand context</text>
<text class="step-subtitle" x="944" y="224">expand_links</text>
<rect class="chip" x="944" y="250" width="164" height="44"/>
<text class="chip-title" x="1026" y="269" text-anchor="middle">top chunks</text>
<text class="chip-text" x="1026" y="287" text-anchor="middle">path + line range</text>
<rect class="chip" x="944" y="314" width="164" height="44"/>
<text class="chip-title" x="1026" y="333" text-anchor="middle">outlinks + inlinks</text>
<text class="chip-text" x="1026" y="351" text-anchor="middle">name, description, via</text>
<path class="arrow" d="M296 280 H348"/>
<path class="arrow" d="M580 280 H632"/>
<path class="arrow" d="M864 280 H916"/>
<path class="arrow" d="M296 280 H348"/>
<path class="arrow" d="M580 280 H632"/>
<path class="arrow" d="M864 280 H916"/>
<rect class="panel" x="142" y="484" width="916" height="76"/>
<text class="note" x="190" y="514">Default path</text>
<text class="chip-text" x="190" y="536">BM25 first, vector optional.</text>
<line class="line" x1="410" y1="500" x2="410" y2="544"/>
<text class="chip-title" x="454" y="514">BM25 is enabled by default</text>
<text class="chip-text" x="454" y="536">embedding_store is empty unless configured.</text>
<line class="line" x1="720" y1="500" x2="720" y2="544"/>
<text class="chip-title" x="764" y="514">Results stay compact first</text>
<text class="chip-text" x="764" y="536">Use read or traverse for deeper expansion.</text>
<rect class="panel" x="142" y="484" width="916" height="76"/>
<text class="note" x="190" y="514">Rebuild scope</text>
<text class="chip-text" x="190" y="536">reindex adds resource + JSONL.</text>
<line class="line" x1="410" y1="500" x2="410" y2="544"/>
<text class="chip-title" x="454" y="514">BM25 is enabled by default</text>
<text class="chip-text" x="454" y="536">Recall cap: 200; embeddings opt-in.</text>
<line class="line" x1="720" y1="500" x2="720" y2="544"/>
<text class="chip-title" x="764" y="514">Results stay compact first</text>
<text class="chip-text" x="764" y="536">Use read or traverse for deeper expansion.</text>
<path class="soft-arrow" d="M1026 410 C1026 456 748 452 748 410"/>
<text class="note" x="888" y="454" text-anchor="middle">link expansion is contextual, not a full-workspace dump</text>
<path class="soft-arrow" d="M1026 410 C1026 456 748 452 748 410"/>
<text class="note" x="888" y="454" text-anchor="middle">link expansion is contextual, not a full-workspace dump</text>
</svg>

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 7 KiB

After

Width:  |  Height:  |  Size: 7 KiB

154
docs/figure/auto-memory-resource.svg
View file

@ -1,91 +1,79 @@
<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="640" viewBox="0 0 1200 640" role="img" aria-labelledby="title desc">
<title id="title">ReMe auto memory and auto resource flow</title>
<desc id="desc">A concise flow where auto memory and auto resource both create daily cards, which are indexed in the daily memory layer and then used by dream and search.</desc>
<defs>
<style>
.bg { fill: #fffdf8; }
.title { font: 700 30px "Comic Sans MS", "Bradley Hand", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #1f2430; }
.subtitle { font: 14px "Comic Sans MS", "Bradley Hand", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #556276; }
.step-num { font: 700 12px "Comic Sans MS", "Bradley Hand", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #ffffff; }
.step-title { font: 700 18px "Comic Sans MS", "Bradley Hand", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #1f2430; }
.step-subtitle { font: 13px "Comic Sans MS", "Bradley Hand", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #556276; }
.chip-title { font: 700 13px "Comic Sans MS", "Bradley Hand", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #1f2430; }
.chip-text { font: 12px "Comic Sans MS", "Bradley Hand", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #5e6a7c; }
.note { font: 12px "Comic Sans MS", "Bradley Hand", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #4f5c6f; }
.panel { fill: #ffffff; stroke: #1f2430; stroke-width: 2.2; rx: 18; ry: 18; stroke-linecap: round; stroke-linejoin: round; }
.chip { fill: #f8fbff; stroke: #1f2430; stroke-width: 1.6; rx: 11; ry: 11; stroke-linecap: round; stroke-linejoin: round; stroke-dasharray: 6 5; }
.badge { fill: #44546a; }
.arrow { stroke: #7f8b9d; stroke-width: 1.45; fill: none; stroke-linecap: round; stroke-linejoin: round; marker-end: url(#arrow); }
.soft-arrow { stroke: #a3adbd; stroke-width: 1.25; stroke-dasharray: 6 6; fill: none; stroke-linecap: round; stroke-linejoin: round; marker-end: url(#arrow-soft); }
.line { stroke: #a3adbd; stroke-width: 1.25; stroke-linecap: round; }
</style>
<marker id="arrow" markerWidth="6" markerHeight="6" refX="5" refY="2" orient="auto" markerUnits="strokeWidth">
<path d="M0,0 L0,4 L5,2 z" fill="#7f8b9d"/>
</marker>
<marker id="arrow-soft" markerWidth="6" markerHeight="6" refX="5" refY="2" orient="auto" markerUnits="strokeWidth">
<path d="M0,0 L0,4 L5,2 z" fill="#a3adbd"/>
</marker>
</defs>
<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="640" viewBox="0 0 1200 640" role="img"
aria-labelledby="title desc">
<title id="title">ReMe auto memory and auto resource flow</title>
<desc id="desc">A concise flow where auto memory and auto resource both create daily cards, which are indexed in the
daily memory layer and then used by dream and search.
</desc>
<defs>
<style>.bg { fill: #fffdf8; } .title { font: 700 30px "Comic Sans MS", "Bradley Hand", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #1f2430; } .subtitle { font: 14px "Comic Sans MS", "Bradley Hand", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #556276; } .step-num { font: 700 12px "Comic Sans MS", "Bradley Hand", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #ffffff; } .step-title { font: 700 18px "Comic Sans MS", "Bradley Hand", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #1f2430; } .step-subtitle { font: 13px "Comic Sans MS", "Bradley Hand", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #556276; } .chip-title { font: 700 13px "Comic Sans MS", "Bradley Hand", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #1f2430; } .chip-text { font: 12px "Comic Sans MS", "Bradley Hand", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #5e6a7c; } .note { font: 12px "Comic Sans MS", "Bradley Hand", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #4f5c6f; } .panel { fill: #ffffff; stroke: #1f2430; stroke-width: 2.2; rx: 18; ry: 18; stroke-linecap: round; stroke-linejoin: round; } .chip { fill: #f8fbff; stroke: #1f2430; stroke-width: 1.6; rx: 11; ry: 11; stroke-linecap: round; stroke-linejoin: round; stroke-dasharray: 6 5; } .badge { fill: #44546a; } .arrow { stroke: #7f8b9d; stroke-width: 1.45; fill: none; stroke-linecap: round; stroke-linejoin: round; marker-end: url(#arrow); } .soft-arrow { stroke: #a3adbd; stroke-width: 1.25; stroke-dasharray: 6 6; fill: none; stroke-linecap: round; stroke-linejoin: round; marker-end: url(#arrow-soft); } .line { stroke: #a3adbd; stroke-width: 1.25; stroke-linecap: round; }</style>
<marker id="arrow" markerWidth="6" markerHeight="6" refX="5" refY="2" orient="auto" markerUnits="strokeWidth">
<path d="M0,0 L0,4 L5,2 z" fill="#7f8b9d"/>
</marker>
<marker id="arrow-soft" markerWidth="6" markerHeight="6" refX="5" refY="2" orient="auto"
markerUnits="strokeWidth">
<path d="M0,0 L0,4 L5,2 z" fill="#a3adbd"/>
</marker>
</defs>
<rect class="bg" x="0" y="0" width="1200" height="640"/>
<text class="title" x="600" y="54" text-anchor="middle">Auto Memory &amp; Auto Resource</text>
<text class="subtitle" x="600" y="80" text-anchor="middle">Two ingestion paths create daily cards, then share one daily index and downstream memory flow.</text>
<rect class="bg" x="0" y="0" width="1200" height="640"/>
<text class="title" x="600" y="54" text-anchor="middle">Auto Memory &amp; Auto Resource</text>
<text class="subtitle" x="600" y="80" text-anchor="middle">Two ingestion paths create daily cards, then share one daily index and downstream memory flow.</text>
<rect class="panel" x="84" y="132" width="300" height="300"/>
<circle class="badge" cx="118" cy="170" r="15"/>
<text class="step-num" x="118" y="174" text-anchor="middle">1</text>
<text class="step-title" x="146" y="176">Inputs</text>
<text class="step-subtitle" x="112" y="206">memory + resource</text>
<rect class="chip" x="112" y="234" width="244" height="54"/>
<text class="chip-title" x="234" y="255" text-anchor="middle">Auto Memory</text>
<text class="chip-text" x="234" y="273" text-anchor="middle">conversation -> session daily card</text>
<rect class="chip" x="112" y="312" width="244" height="54"/>
<text class="chip-title" x="234" y="333" text-anchor="middle">Auto Resource</text>
<text class="chip-text" x="234" y="351" text-anchor="middle">dated file -> resource daily card</text>
<rect class="chip" x="112" y="388" width="244" height="28"/>
<text class="chip-text" x="234" y="407" text-anchor="middle">original sources remain verifiable</text>
<rect class="panel" x="84" y="132" width="300" height="300"/>
<circle class="badge" cx="118" cy="170" r="15"/>
<text class="step-num" x="118" y="174" text-anchor="middle">1</text>
<text class="step-title" x="146" y="176">Inputs</text>
<text class="step-subtitle" x="112" y="206">memory + resource</text>
<rect class="chip" x="112" y="234" width="244" height="54"/>
<text class="chip-title" x="234" y="255" text-anchor="middle">Auto Memory</text>
<text class="chip-text" x="234" y="273" text-anchor="middle">conversation -> topic-named card</text>
<rect class="chip" x="112" y="312" width="244" height="54"/>
<text class="chip-title" x="234" y="333" text-anchor="middle">Auto Resource</text>
<text class="chip-text" x="234" y="351" text-anchor="middle">source file -> topic-named card</text>
<rect class="chip" x="112" y="388" width="244" height="28"/>
<text class="chip-text" x="234" y="407" text-anchor="middle">original sources remain verifiable</text>
<rect class="panel" x="450" y="132" width="300" height="300"/>
<circle class="badge" cx="484" cy="170" r="15"/>
<text class="step-num" x="484" y="174" text-anchor="middle">2</text>
<text class="step-title" x="512" y="176">Daily Memory Layer</text>
<text class="step-subtitle" x="478" y="206">daily/&lt;date&gt;/</text>
<rect class="chip" x="478" y="234" width="244" height="54"/>
<text class="chip-title" x="600" y="255" text-anchor="middle">daily cards</text>
<text class="chip-text" x="600" y="273" text-anchor="middle">facts, context, actions</text>
<rect class="chip" x="478" y="312" width="244" height="54"/>
<text class="chip-title" x="600" y="333" text-anchor="middle">day index</text>
<text class="chip-text" x="600" y="351" text-anchor="middle">daily/&lt;date&gt;.md links cards</text>
<rect class="chip" x="478" y="388" width="244" height="28"/>
<text class="chip-text" x="600" y="407" text-anchor="middle">one readable daily memory stream</text>
<rect class="panel" x="450" y="132" width="300" height="300"/>
<circle class="badge" cx="484" cy="170" r="15"/>
<text class="step-num" x="484" y="174" text-anchor="middle">2</text>
<text class="step-title" x="512" y="176">Daily Memory Layer</text>
<text class="step-subtitle" x="478" y="206">daily/&lt;date&gt;/</text>
<rect class="chip" x="478" y="234" width="244" height="54"/>
<text class="chip-title" x="600" y="255" text-anchor="middle">daily cards</text>
<text class="chip-text" x="600" y="273" text-anchor="middle">facts, context, actions</text>
<rect class="chip" x="478" y="312" width="244" height="54"/>
<text class="chip-title" x="600" y="333" text-anchor="middle">day index</text>
<text class="chip-text" x="600" y="351" text-anchor="middle">daily/&lt;date&gt;.md links cards</text>
<rect class="chip" x="478" y="388" width="244" height="28"/>
<text class="chip-text" x="600" y="407" text-anchor="middle">one readable daily memory stream</text>
<rect class="panel" x="816" y="132" width="300" height="300"/>
<circle class="badge" cx="850" cy="170" r="15"/>
<text class="step-num" x="850" y="174" text-anchor="middle">3</text>
<text class="step-title" x="878" y="176">Downstream</text>
<text class="step-subtitle" x="844" y="206">dream + search</text>
<rect class="chip" x="844" y="234" width="244" height="54"/>
<text class="chip-title" x="966" y="255" text-anchor="middle">Auto Dream</text>
<text class="chip-text" x="966" y="273" text-anchor="middle">daily material -> digest memory</text>
<rect class="chip" x="844" y="312" width="244" height="54"/>
<text class="chip-title" x="966" y="333" text-anchor="middle">Memory Search</text>
<text class="chip-text" x="966" y="351" text-anchor="middle">retrieve daily and digest nodes</text>
<rect class="chip" x="844" y="388" width="244" height="28"/>
<text class="chip-text" x="966" y="407" text-anchor="middle">daily is the shared ingestion layer</text>
<rect class="panel" x="816" y="132" width="300" height="300"/>
<circle class="badge" cx="850" cy="170" r="15"/>
<text class="step-num" x="850" y="174" text-anchor="middle">3</text>
<text class="step-title" x="878" y="176">Downstream</text>
<text class="step-subtitle" x="844" y="206">dream + search</text>
<rect class="chip" x="844" y="234" width="244" height="54"/>
<text class="chip-title" x="966" y="255" text-anchor="middle">Auto Dream</text>
<text class="chip-text" x="966" y="273" text-anchor="middle">daily material -> digest memory</text>
<rect class="chip" x="844" y="312" width="244" height="54"/>
<text class="chip-title" x="966" y="333" text-anchor="middle">Memory Search</text>
<text class="chip-text" x="966" y="351" text-anchor="middle">retrieve daily and digest nodes</text>
<rect class="chip" x="844" y="388" width="244" height="28"/>
<text class="chip-text" x="966" y="407" text-anchor="middle">daily is the shared ingestion layer</text>
<path class="arrow" d="M384 282 H450"/>
<path class="arrow" d="M750 282 H816"/>
<path class="arrow" d="M384 282 H450"/>
<path class="arrow" d="M750 282 H816"/>
<rect class="panel" x="126" y="502" width="948" height="82"/>
<text class="note" x="176" y="532">Conversation source</text>
<text class="chip-text" x="176" y="554">session/dialog/&lt;session_id&gt;.jsonl</text>
<line class="line" x1="454" y1="518" x2="454" y2="566"/>
<text class="chip-title" x="498" y="532">Resource source</text>
<text class="chip-text" x="498" y="554">resource/&lt;date&gt;/&lt;resource_file&gt;</text>
<line class="line" x1="796" y1="518" x2="796" y2="566"/>
<text class="chip-title" x="838" y="532">Daily output</text>
<text class="chip-text" x="838" y="554">daily cards plus daily/&lt;date&gt;.md</text>
<rect class="panel" x="126" y="502" width="948" height="82"/>
<text class="note" x="176" y="532">Conversation source</text>
<text class="chip-text" x="176" y="554">session/dialog/&lt;session_id&gt;.jsonl</text>
<line class="line" x1="454" y1="518" x2="454" y2="566"/>
<text class="chip-title" x="498" y="532">Resource source</text>
<text class="chip-text" x="498" y="554">resource/[&lt;date&gt;/]&lt;resource_file&gt;</text>
<line class="line" x1="796" y1="518" x2="796" y2="566"/>
<text class="chip-title" x="838" y="532">Daily output</text>
<text class="chip-text" x="838" y="554">daily/&lt;date&gt;/&lt;name&gt;.md</text>
<path class="soft-arrow" d="M966 432 C966 474 600 474 600 432"/>
<text class="note" x="782" y="478" text-anchor="middle">downstream flows read the same daily memory layer</text>
<path class="soft-arrow" d="M966 432 C966 474 600 474 600 432"/>
<text class="note" x="782" y="478" text-anchor="middle">downstream flows read the same daily memory layer</text>
</svg>

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 6.7 KiB

After

Width:  |  Height:  |  Size: 6.8 KiB

166
docs/figure/design-philosophy.svg
View file

@ -1,97 +1,83 @@
<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="520" viewBox="0 0 1200 520" role="img" aria-labelledby="title desc">
<title id="title">ReMe design philosophy</title>
<desc id="desc">A simple diagram showing ReMe's design philosophy: file-native memory, progressive abstraction, and explicit relationship graph for agents.</desc>
<defs>
<style>
.bg { fill: #ffffff; }
.title { font: 700 30px "Comic Sans MS", "Bradley Hand", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #1f2430; }
.subtitle { font: 14px "Comic Sans MS", "Bradley Hand", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #556276; }
.panel { fill: #ffffff; stroke: #1f2430; stroke-width: 2.2; stroke-linecap: round; stroke-linejoin: round; }
.panel-blue { fill: #eef7ff; stroke: #1f2430; stroke-width: 2.2; stroke-linecap: round; stroke-linejoin: round; }
.panel-green { fill: #f0fbf5; stroke: #1f2430; stroke-width: 2.2; stroke-linecap: round; stroke-linejoin: round; }
.panel-yellow { fill: #fff7e5; stroke: #1f2430; stroke-width: 2.2; stroke-linecap: round; stroke-linejoin: round; }
.label { font: 700 18px "Comic Sans MS", "Bradley Hand", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #1f2430; }
.small { font: 13px "Comic Sans MS", "Bradley Hand", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #556276; }
.tiny { font: 12px "Comic Sans MS", "Bradley Hand", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #5e6a7c; }
.chip { fill: #ffffff; stroke: #1f2430; stroke-width: 1.6; stroke-linecap: round; stroke-linejoin: round; stroke-dasharray: 6 5; }
.chip-text { font: 700 13px "Comic Sans MS", "Bradley Hand", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #1f2430; }
.arrow { stroke: #7f8b9d; stroke-width: 1.45; fill: none; stroke-linecap: round; stroke-linejoin: round; marker-end: url(#arrow); }
.soft-arrow { stroke: #a3adbd; stroke-width: 1.25; fill: none; stroke-dasharray: 6 6; stroke-linecap: round; stroke-linejoin: round; marker-end: url(#arrow-soft); }
.node { fill: #ffffff; stroke: #1f2430; stroke-width: 1.6; }
.link { stroke: #a3adbd; stroke-width: 1.45; fill: none; stroke-linecap: round; stroke-linejoin: round; }
.file-line { stroke: #7f8b9d; stroke-width: 1.45; stroke-linecap: round; }
</style>
<marker id="arrow" markerWidth="6" markerHeight="6" refX="5" refY="2" orient="auto" markerUnits="strokeWidth">
<path d="M0,0 L0,4 L5,2 z" fill="#7f8b9d"/>
</marker>
<marker id="arrow-soft" markerWidth="6" markerHeight="6" refX="5" refY="2" orient="auto" markerUnits="strokeWidth">
<path d="M0,0 L0,4 L5,2 z" fill="#a3adbd"/>
</marker>
</defs>
<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="520" viewBox="0 0 1200 520" role="img"
aria-labelledby="title desc">
<title id="title">ReMe design philosophy</title>
<desc id="desc">A simple diagram showing ReMe's design philosophy: file-native memory, progressive abstraction, and
explicit relationship graph for agents.
</desc>
<defs>
<style>.bg { fill: #ffffff; } .title { font: 700 30px "Comic Sans MS", "Bradley Hand", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #1f2430; } .subtitle { font: 14px "Comic Sans MS", "Bradley Hand", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #556276; } .panel { fill: #ffffff; stroke: #1f2430; stroke-width: 2.2; stroke-linecap: round; stroke-linejoin: round; } .panel-blue { fill: #eef7ff; stroke: #1f2430; stroke-width: 2.2; stroke-linecap: round; stroke-linejoin: round; } .panel-green { fill: #f0fbf5; stroke: #1f2430; stroke-width: 2.2; stroke-linecap: round; stroke-linejoin: round; } .panel-yellow { fill: #fff7e5; stroke: #1f2430; stroke-width: 2.2; stroke-linecap: round; stroke-linejoin: round; } .label { font: 700 18px "Comic Sans MS", "Bradley Hand", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #1f2430; } .small { font: 13px "Comic Sans MS", "Bradley Hand", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #556276; } .tiny { font: 12px "Comic Sans MS", "Bradley Hand", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #5e6a7c; } .chip { fill: #ffffff; stroke: #1f2430; stroke-width: 1.6; stroke-linecap: round; stroke-linejoin: round; stroke-dasharray: 6 5; } .chip-text { font: 700 13px "Comic Sans MS", "Bradley Hand", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #1f2430; } .arrow { stroke: #7f8b9d; stroke-width: 1.45; fill: none; stroke-linecap: round; stroke-linejoin: round; marker-end: url(#arrow); } .soft-arrow { stroke: #a3adbd; stroke-width: 1.25; fill: none; stroke-dasharray: 6 6; stroke-linecap: round; stroke-linejoin: round; marker-end: url(#arrow-soft); } .node { fill: #ffffff; stroke: #1f2430; stroke-width: 1.6; } .link { stroke: #a3adbd; stroke-width: 1.45; fill: none; stroke-linecap: round; stroke-linejoin: round; } .file-line { stroke: #7f8b9d; stroke-width: 1.45; stroke-linecap: round; }</style>
<marker id="arrow" markerWidth="6" markerHeight="6" refX="5" refY="2" orient="auto" markerUnits="strokeWidth">
<path d="M0,0 L0,4 L5,2 z" fill="#7f8b9d"/>
</marker>
<marker id="arrow-soft" markerWidth="6" markerHeight="6" refX="5" refY="2" orient="auto"
markerUnits="strokeWidth">
<path d="M0,0 L0,4 L5,2 z" fill="#a3adbd"/>
</marker>
</defs>
<rect class="bg" x="0" y="0" width="1200" height="520"/>
<text class="title" x="600" y="54" text-anchor="middle">ReMe Design Philosophy</text>
<text class="subtitle" x="600" y="80" text-anchor="middle">File-native memory, progressive abstraction, and explicit links for reusable agent context.</text>
<rect class="bg" x="0" y="0" width="1200" height="520"/>
<text class="title" x="600" y="54" text-anchor="middle">ReMe Design Philosophy</text>
<text class="subtitle" x="600" y="80" text-anchor="middle">File-native memory, progressive abstraction, and explicit links for reusable agent context.</text>
<rect class="panel-blue" x="64" y="134" width="304" height="220" rx="14"/>
<text class="label" x="216" y="170" text-anchor="middle">Foundation: Memory as File</text>
<text class="small" x="216" y="196" text-anchor="middle">Readable, editable knowledge assets</text>
<g transform="translate(126 224)">
<rect class="panel" x="0" y="0" width="120" height="82" rx="8"/>
<path class="file-line" d="M22 26 H98"/>
<path class="file-line" d="M22 43 H86"/>
<path class="file-line" d="M22 60 H72"/>
<rect class="chip" x="136" y="6" width="96" height="28" rx="8"/>
<text class="chip-text" x="184" y="25" text-anchor="middle">Markdown</text>
<rect class="chip" x="136" y="48" width="96" height="28" rx="8"/>
<text class="chip-text" x="184" y="67" text-anchor="middle">YAML/JSONL</text>
</g>
<text class="tiny" x="216" y="332" text-anchor="middle">Human-readable. Agent-operable.</text>
<rect class="panel-blue" x="64" y="134" width="304" height="220" rx="14"/>
<text class="label" x="216" y="170" text-anchor="middle">Foundation: Memory as File</text>
<text class="small" x="216" y="196" text-anchor="middle">Readable, editable knowledge assets</text>
<g transform="translate(126 224)">
<rect class="panel" x="0" y="0" width="120" height="82" rx="8"/>
<path class="file-line" d="M22 26 H98"/>
<path class="file-line" d="M22 43 H86"/>
<path class="file-line" d="M22 60 H72"/>
<rect class="chip" x="136" y="6" width="96" height="28" rx="8"/>
<text class="chip-text" x="184" y="25" text-anchor="middle">Markdown</text>
<rect class="chip" x="136" y="48" width="96" height="28" rx="8"/>
<text class="chip-text" x="184" y="67" text-anchor="middle">YAML/JSONL</text>
</g>
<text class="tiny" x="216" y="332" text-anchor="middle">Human-readable. Agent-operable.</text>
<rect class="panel-yellow" x="448" y="134" width="304" height="220" rx="14"/>
<text class="label" x="600" y="170" text-anchor="middle">Core: Progressive Abstraction</text>
<text class="small" x="600" y="196" text-anchor="middle">From raw material to durable memory</text>
<g transform="translate(472 235)">
<rect class="chip" x="0" y="0" width="66" height="42" rx="10"/>
<text class="chip-text" x="33" y="26" text-anchor="middle">Raw</text>
<rect class="chip" x="95" y="0" width="66" height="42" rx="10"/>
<text class="chip-text" x="128" y="26" text-anchor="middle">Daily</text>
<rect class="chip" x="190" y="0" width="66" height="42" rx="10"/>
<text class="chip-text" x="223" y="26" text-anchor="middle">Digest</text>
<path class="arrow" d="M68 21 H89"/>
<path class="arrow" d="M163 21 H184"/>
</g>
<text class="tiny" x="600" y="310" text-anchor="middle">session/ + resource/ -> daily/ -> digest/</text>
<text class="tiny" x="600" y="332" text-anchor="middle">Continuous consolidation, not one-shot summary.</text>
<rect class="panel-yellow" x="448" y="134" width="304" height="220" rx="14"/>
<text class="label" x="600" y="170" text-anchor="middle">Core: Progressive Abstraction</text>
<text class="small" x="600" y="196" text-anchor="middle">From raw material to durable memory</text>
<g transform="translate(472 235)">
<rect class="chip" x="0" y="0" width="66" height="42" rx="10"/>
<text class="chip-text" x="33" y="26" text-anchor="middle">Raw</text>
<rect class="chip" x="95" y="0" width="66" height="42" rx="10"/>
<text class="chip-text" x="128" y="26" text-anchor="middle">Daily</text>
<rect class="chip" x="190" y="0" width="66" height="42" rx="10"/>
<text class="chip-text" x="223" y="26" text-anchor="middle">Digest</text>
<path class="arrow" d="M68 21 H89"/>
<path class="arrow" d="M163 21 H184"/>
</g>
<text class="tiny" x="600" y="310" text-anchor="middle">session/resource -> daily -> digest</text>
<text class="tiny" x="600" y="332" text-anchor="middle">Continuous consolidation; not one-shot.</text>
<rect class="panel-green" x="832" y="134" width="304" height="220" rx="14"/>
<text class="label" x="984" y="170" text-anchor="middle">Innovation: Link Graph</text>
<text class="small" x="984" y="196" text-anchor="middle">Explicit links expand context</text>
<g transform="translate(930 207) scale(0.74)">
<path class="link" d="M74 40 L26 90"/>
<path class="link" d="M74 40 L130 84"/>
<path class="link" d="M26 90 L130 84"/>
<path class="link" d="M74 40 L152 26"/>
<circle class="node" cx="74" cy="40" r="24"/>
<circle class="node" cx="26" cy="90" r="20"/>
<circle class="node" cx="130" cy="84" r="20"/>
<circle class="node" cx="152" cy="26" r="18"/>
<text class="chip-text" x="74" y="38" text-anchor="middle">[[ ]]</text>
<text class="tiny" x="74" y="55" text-anchor="middle">Node</text>
<text class="tiny" x="26" y="95" text-anchor="middle">Src</text>
<text class="tiny" x="130" y="89" text-anchor="middle">Risk</text>
<text class="tiny" x="152" y="31" text-anchor="middle">Dep</text>
</g>
<text class="tiny" x="984" y="318" text-anchor="middle">Beyond similarity: source, cause, dependency, risk.</text>
<text class="tiny" x="984" y="338" text-anchor="middle">Wikilinks guide expansion across nodes.</text>
<rect class="panel-green" x="832" y="134" width="304" height="220" rx="14"/>
<text class="label" x="984" y="170" text-anchor="middle">Innovation: Link Graph</text>
<text class="small" x="984" y="196" text-anchor="middle">Explicit links expand context</text>
<g transform="translate(930 207) scale(0.74)">
<path class="link" d="M74 40 L26 90"/>
<path class="link" d="M74 40 L130 84"/>
<path class="link" d="M26 90 L130 84"/>
<path class="link" d="M74 40 L152 26"/>
<circle class="node" cx="74" cy="40" r="24"/>
<circle class="node" cx="26" cy="90" r="20"/>
<circle class="node" cx="130" cy="84" r="20"/>
<circle class="node" cx="152" cy="26" r="18"/>
<text class="chip-text" x="74" y="38" text-anchor="middle">[[ ]]</text>
<text class="tiny" x="74" y="55" text-anchor="middle">Node</text>
<text class="tiny" x="26" y="95" text-anchor="middle">Src</text>
<text class="tiny" x="130" y="89" text-anchor="middle">Risk</text>
<text class="tiny" x="152" y="31" text-anchor="middle">Dep</text>
</g>
<text class="tiny" x="984" y="318" text-anchor="middle">Source · cause · dependency · risk</text>
<text class="tiny" x="984" y="338" text-anchor="middle">Wikilinks guide expansion across nodes.</text>
<path class="arrow" d="M368 244 H448"/>
<path class="arrow" d="M752 244 H832"/>
<path class="arrow" d="M368 244 H448"/>
<path class="arrow" d="M752 244 H832"/>
<rect class="panel" x="220" y="414" width="760" height="56" rx="14"/>
<text class="small" x="600" y="438" text-anchor="middle">One shared file tree acts as both memory store and operating surface.</text>
<text class="chip-text" x="600" y="460" text-anchor="middle">capture -> refine -> link -> retrieve -> expand</text>
<path class="soft-arrow" d="M216 354 C216 392 428 392 454 414"/>
<path class="soft-arrow" d="M600 354 V414"/>
<path class="soft-arrow" d="M984 354 C984 392 772 392 746 414"/>
<rect class="panel" x="220" y="414" width="760" height="56" rx="14"/>
<text class="small" x="600" y="438" text-anchor="middle">One shared file tree acts as both memory store and operating surface.</text>
<text class="chip-text" x="600" y="460" text-anchor="middle">capture -> refine -> link -> retrieve -> expand</text>
<path class="soft-arrow" d="M216 354 C216 392 428 392 454 414"/>
<path class="soft-arrow" d="M600 354 V414"/>
<path class="soft-arrow" d="M984 354 C984 392 772 392 746 414"/>
</svg>

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 6.8 KiB

After

Width:  |  Height:  |  Size: 6.9 KiB

279
docs/figure/framework-structure.svg
View file

@ -1,158 +1,149 @@
<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="920" viewBox="0 0 1200 920" role="img" aria-labelledby="title desc">
<title id="title">ReMe framework structure</title>
<desc id="desc">An architectural map of ReMe from file-backed workspace storage through knowledge kernel, workflows, application wiring, and external service surfaces.</desc>
<defs>
<linearGradient id="paper" x1="0" y1="0" x2="1" y2="1">
<stop offset="0" stop-color="#fbfaf6"/>
<stop offset="0.55" stop-color="#f5f7fb"/>
<stop offset="1" stop-color="#eef7f4"/>
</linearGradient>
<linearGradient id="serviceGrad" x1="0" y1="0" x2="1" y2="0">
<stop offset="0" stop-color="#d9f3ec"/>
<stop offset="1" stop-color="#dcecf7"/>
</linearGradient>
<linearGradient id="appGrad" x1="0" y1="0" x2="1" y2="0">
<stop offset="0" stop-color="#e5e8fb"/>
<stop offset="1" stop-color="#f1e4f5"/>
</linearGradient>
<linearGradient id="jobGrad" x1="0" y1="0" x2="1" y2="0">
<stop offset="0" stop-color="#fae4d8"/>
<stop offset="1" stop-color="#f4eccd"/>
</linearGradient>
<linearGradient id="kernelGrad" x1="0" y1="0" x2="1" y2="0">
<stop offset="0" stop-color="#d9f1f4"/>
<stop offset="1" stop-color="#e1e8f7"/>
</linearGradient>
<linearGradient id="workspaceGrad" x1="0" y1="0" x2="1" y2="0">
<stop offset="0" stop-color="#f0e5d3"/>
<stop offset="1" stop-color="#e3efd9"/>
</linearGradient>
<filter id="softShadow" x="-8%" y="-18%" width="116%" height="145%">
<feDropShadow dx="0" dy="16" stdDeviation="16" flood-color="#1c2b3a" flood-opacity="0.13"/>
</filter>
<filter id="nodeShadow" x="-15%" y="-30%" width="130%" height="170%">
<feDropShadow dx="0" dy="8" stdDeviation="8" flood-color="#1c2b3a" flood-opacity="0.12"/>
</filter>
<style>
.bg { fill: url(#paper); }
.grain { fill: none; stroke: #d9ded8; stroke-width: 1; opacity: 0.38; }
text { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Arial, sans-serif; }
.title { font-size: 30px; font-weight: 800; fill: #172033; }
.subtitle { font-size: 14px; fill: #667489; }
.layer-title { font-size: 18px; font-weight: 800; fill: #263548; }
.layer-note { font-size: 13px; fill: rgba(38,53,72,0.72); }
.section-label { font-size: 11px; font-weight: 800; fill: #647187; letter-spacing: 1.8px; }
.node-title { font-size: 14px; font-weight: 700; fill: #1d2838; }
.node-text { font-size: 12px; fill: #667489; }
.micro { font-size: 11px; fill: #728096; }
.plate { filter: url(#softShadow); }
.plate-bg { fill: #ffffff; stroke: rgba(52, 65, 84, 0.12); stroke-width: 1; }
.side { opacity: 0.18; }
.node { fill: #ffffff; stroke: rgba(90, 105, 128, 0.22); stroke-width: 1; filter: url(#nodeShadow); }
</style>
</defs>
<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="920" viewBox="0 0 1200 920" role="img"
aria-labelledby="title desc">
<title id="title">ReMe framework structure</title>
<desc id="desc">An architectural map of ReMe from file-backed workspace storage through knowledge kernel, workflows,
application wiring, and external service surfaces.
</desc>
<defs>
<linearGradient id="paper" x1="0" y1="0" x2="1" y2="1">
<stop offset="0" stop-color="#fbfaf6"/>
<stop offset="0.55" stop-color="#f5f7fb"/>
<stop offset="1" stop-color="#eef7f4"/>
</linearGradient>
<linearGradient id="serviceGrad" x1="0" y1="0" x2="1" y2="0">
<stop offset="0" stop-color="#d9f3ec"/>
<stop offset="1" stop-color="#dcecf7"/>
</linearGradient>
<linearGradient id="appGrad" x1="0" y1="0" x2="1" y2="0">
<stop offset="0" stop-color="#e5e8fb"/>
<stop offset="1" stop-color="#f1e4f5"/>
</linearGradient>
<linearGradient id="jobGrad" x1="0" y1="0" x2="1" y2="0">
<stop offset="0" stop-color="#fae4d8"/>
<stop offset="1" stop-color="#f4eccd"/>
</linearGradient>
<linearGradient id="kernelGrad" x1="0" y1="0" x2="1" y2="0">
<stop offset="0" stop-color="#d9f1f4"/>
<stop offset="1" stop-color="#e1e8f7"/>
</linearGradient>
<linearGradient id="workspaceGrad" x1="0" y1="0" x2="1" y2="0">
<stop offset="0" stop-color="#f0e5d3"/>
<stop offset="1" stop-color="#e3efd9"/>
</linearGradient>
<filter id="softShadow" x="-8%" y="-18%" width="116%" height="145%">
<feDropShadow dx="0" dy="16" stdDeviation="16" flood-color="#1c2b3a" flood-opacity="0.13"/>
</filter>
<filter id="nodeShadow" x="-15%" y="-30%" width="130%" height="170%">
<feDropShadow dx="0" dy="8" stdDeviation="8" flood-color="#1c2b3a" flood-opacity="0.12"/>
</filter>
<style>.bg { fill: url(#paper); } .grain { fill: none; stroke: #d9ded8; stroke-width: 1; opacity: 0.38; } text { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Arial, sans-serif; } .title { font-size: 30px; font-weight: 800; fill: #172033; } .subtitle { font-size: 14px; fill: #667489; } .layer-title { font-size: 18px; font-weight: 800; fill: #263548; } .layer-note { font-size: 13px; fill: rgba(38,53,72,0.72); } .section-label { font-size: 11px; font-weight: 800; fill: #647187; letter-spacing: 1.8px; } .node-title { font-size: 14px; font-weight: 700; fill: #1d2838; } .node-text { font-size: 12px; fill: #667489; } .micro { font-size: 11px; fill: #728096; } .plate { filter: url(#softShadow); } .plate-bg { fill: #ffffff; stroke: rgba(52, 65, 84, 0.12); stroke-width: 1; } .side { opacity: 0.18; } .node { fill: #ffffff; stroke: rgba(90, 105, 128, 0.22); stroke-width: 1; filter: url(#nodeShadow); }</style>
</defs>
<rect class="bg" width="1200" height="920"/>
<path class="grain" d="M98 138 C246 104 337 155 475 121 C616 86 752 124 890 96 C1019 70 1082 98 1136 126"/>
<path class="grain" d="M64 768 C218 720 374 790 514 742 C660 692 812 740 966 706 C1066 684 1118 708 1146 732"/>
<rect class="bg" width="1200" height="920"/>
<path class="grain" d="M98 138 C246 104 337 155 475 121 C616 86 752 124 890 96 C1019 70 1082 98 1136 126"/>
<path class="grain" d="M64 768 C218 720 374 790 514 742 C660 692 812 740 966 706 C1066 684 1118 708 1146 732"/>
<text class="title" x="600" y="56" text-anchor="middle">ReMe Framework Structure</text>
<text class="subtitle" x="600" y="83" text-anchor="middle">File-backed memory, searchable knowledge kernel, composable jobs, app wiring, and public service surfaces.</text>
<text class="title" x="600" y="56" text-anchor="middle">ReMe Framework Structure</text>
<text class="subtitle" x="600" y="83" text-anchor="middle">File-backed memory, searchable knowledge kernel, composable jobs, app wiring, and public service surfaces.</text>
<g class="plate" transform="translate(0,0)">
<path class="side" d="M126 196 L1074 196 L1042 226 L158 226 Z" fill="#83cbbb"/>
<rect class="plate-bg" x="126" y="128" width="948" height="96" rx="18"/>
<rect x="126" y="128" width="280" height="96" rx="18" fill="url(#serviceGrad)"/>
<text class="layer-title" x="178" y="166">Service</text>
<text class="layer-note" x="178" y="188">Public interfaces</text>
<g class="plate" transform="translate(0,0)">
<path class="side" d="M126 196 L1074 196 L1042 226 L158 226 Z" fill="#83cbbb"/>
<rect class="plate-bg" x="126" y="128" width="948" height="96" rx="18"/>
<rect x="126" y="128" width="280" height="96" rx="18" fill="url(#serviceGrad)"/>
<text class="layer-title" x="178" y="166">Service</text>
<text class="layer-note" x="178" y="188">Public interfaces</text>
<rect class="node" x="436" y="151" width="138" height="50" rx="13"/>
<text class="node-title" x="505" y="172" text-anchor="middle">HTTP API</text>
<text class="node-text" x="505" y="190" text-anchor="middle">server routes</text>
<rect class="node" x="626" y="151" width="138" height="50" rx="13"/>
<text class="node-title" x="695" y="172" text-anchor="middle">MCP Tools</text>
<text class="node-text" x="695" y="190" text-anchor="middle">agent actions</text>
<rect class="node" x="816" y="151" width="138" height="50" rx="13"/>
<text class="node-title" x="885" y="172" text-anchor="middle">CLI Client</text>
<text class="node-text" x="885" y="190" text-anchor="middle">local access</text>
</g>
<rect class="node" x="436" y="151" width="138" height="50" rx="13"/>
<text class="node-title" x="505" y="172" text-anchor="middle">HTTP API</text>
<text class="node-text" x="505" y="190" text-anchor="middle">API + Studio</text>
<rect class="node" x="626" y="151" width="138" height="50" rx="13"/>
<text class="node-title" x="695" y="172" text-anchor="middle">MCP Tools</text>
<text class="node-text" x="695" y="190" text-anchor="middle">agent actions</text>
<rect class="node" x="816" y="151" width="138" height="50" rx="13"/>
<text class="node-title" x="885" y="172" text-anchor="middle">CLI Client</text>
<text class="node-text" x="885" y="190" text-anchor="middle">service calls</text>
</g>
<g class="plate" transform="translate(0,0)">
<path class="side" d="M94 336 L1106 336 L1074 366 L126 366 Z" fill="#aab5ec"/>
<rect class="plate-bg" x="94" y="264" width="1012" height="100" rx="18"/>
<rect x="94" y="264" width="280" height="100" rx="18" fill="url(#appGrad)"/>
<text class="layer-title" x="146" y="303">Application</text>
<text class="layer-note" x="146" y="325">Config, wiring, lifecycle</text>
<g class="plate" transform="translate(0,0)">
<path class="side" d="M94 336 L1106 336 L1074 366 L126 366 Z" fill="#aab5ec"/>
<rect class="plate-bg" x="94" y="264" width="1012" height="100" rx="18"/>
<rect x="94" y="264" width="280" height="100" rx="18" fill="url(#appGrad)"/>
<text class="layer-title" x="146" y="303">Application</text>
<text class="layer-note" x="146" y="325">Config, wiring, lifecycle</text>
<rect class="node" x="424" y="290" width="122" height="48" rx="12"/>
<text class="node-title" x="485" y="319" text-anchor="middle">Context</text>
<rect class="node" x="574" y="290" width="122" height="48" rx="12"/>
<text class="node-title" x="635" y="319" text-anchor="middle">Wiring</text>
<rect class="node" x="724" y="290" width="122" height="48" rx="12"/>
<text class="node-title" x="785" y="319" text-anchor="middle">Lifecycle</text>
<rect class="node" x="874" y="290" width="122" height="48" rx="12"/>
<text class="node-title" x="935" y="319" text-anchor="middle">Job APIs</text>
</g>
<rect class="node" x="424" y="290" width="122" height="48" rx="12"/>
<text class="node-title" x="485" y="319" text-anchor="middle">Context</text>
<rect class="node" x="574" y="290" width="122" height="48" rx="12"/>
<text class="node-title" x="635" y="319" text-anchor="middle">Wiring</text>
<rect class="node" x="724" y="290" width="122" height="48" rx="12"/>
<text class="node-title" x="785" y="319" text-anchor="middle">Lifecycle</text>
<rect class="node" x="874" y="290" width="122" height="48" rx="12"/>
<text class="node-title" x="935" y="319" text-anchor="middle">Job APIs</text>
</g>
<g class="plate" transform="translate(0,0)">
<path class="side" d="M126 500 L1074 500 L1042 530 L158 530 Z" fill="#e9ad8f"/>
<rect class="plate-bg" x="126" y="404" width="948" height="124" rx="18"/>
<rect x="126" y="404" width="280" height="124" rx="18" fill="url(#jobGrad)"/>
<text class="layer-title" x="178" y="448">Steps / Jobs</text>
<text class="layer-note" x="178" y="470">Composable workflows</text>
<g class="plate" transform="translate(0,0)">
<path class="side" d="M126 500 L1074 500 L1042 530 L158 530 Z" fill="#e9ad8f"/>
<rect class="plate-bg" x="126" y="404" width="948" height="124" rx="18"/>
<rect x="126" y="404" width="280" height="124" rx="18" fill="url(#jobGrad)"/>
<text class="layer-title" x="178" y="448">Steps / Jobs</text>
<text class="layer-note" x="178" y="470">Composable workflows</text>
<rect class="node" x="424" y="428" width="232" height="76" rx="14"/>
<text class="node-title" x="448" y="456">Jobs</text>
<text class="node-text" x="448" y="479">base · stream · background · cron</text>
<rect class="node" x="704" y="428" width="300" height="76" rx="14"/>
<text class="node-title" x="728" y="456">Step Modules</text>
<text class="node-text" x="728" y="479">file_io · index · evolve · transfer · channel · common</text>
</g>
<rect class="node" x="424" y="428" width="232" height="76" rx="14"/>
<text class="node-title" x="448" y="456">Jobs</text>
<text class="node-text" x="448" y="479">base · stream · background · cron</text>
<rect class="node" x="704" y="428" width="300" height="76" rx="14"/>
<text class="node-title" x="728" y="456">Step Modules</text>
<text class="node-text" x="728" y="479">file_io · index · evolve · common</text>
<text class="node-text" x="728" y="497">transfer · cookbook · benchmark</text>
</g>
<g class="plate" transform="translate(0,0)">
<path class="side" d="M94 674 L1106 674 L1074 704 L126 704 Z" fill="#8fcbd5"/>
<rect class="plate-bg" x="94" y="568" width="1012" height="134" rx="18"/>
<rect x="94" y="568" width="280" height="134" rx="18" fill="url(#kernelGrad)"/>
<text class="layer-title" x="146" y="615">Knowledge Kernel</text>
<text class="layer-note" x="146" y="637">Index, watch, schema</text>
<g class="plate" transform="translate(0,0)">
<path class="side" d="M94 674 L1106 674 L1074 704 L126 704 Z" fill="#8fcbd5"/>
<rect class="plate-bg" x="94" y="568" width="1012" height="134" rx="18"/>
<rect x="94" y="568" width="280" height="134" rx="18" fill="url(#kernelGrad)"/>
<text class="layer-title" x="146" y="615">Knowledge Kernel</text>
<text class="layer-note" x="146" y="637">Index, watch, schema</text>
<rect class="node" x="424" y="594" width="228" height="82" rx="14"/>
<text class="node-title" x="448" y="623">Index Stores</text>
<text class="node-text" x="448" y="646">file_store · keyword_index</text>
<text class="node-text" x="448" y="664">embedding_store · file_graph</text>
<rect class="node" x="698" y="594" width="172" height="82" rx="14"/>
<text class="node-title" x="722" y="623">File Watcher</text>
<text class="node-text" x="722" y="646">scanner · chunker</text>
<text class="node-text" x="722" y="664">catalog</text>
<rect class="node" x="916" y="594" width="142" height="82" rx="14"/>
<text class="node-title" x="940" y="623">Memory</text>
<text class="node-text" x="940" y="646">FileNode</text>
<text class="node-text" x="940" y="664">FileChunk · FileLink</text>
</g>
<rect class="node" x="424" y="594" width="228" height="82" rx="14"/>
<text class="node-title" x="448" y="623">Index Stores</text>
<text class="node-text" x="448" y="646">file_store · keyword_index</text>
<text class="node-text" x="448" y="664">embedding_store · file_graph</text>
<rect class="node" x="698" y="594" width="172" height="82" rx="14"/>
<text class="node-title" x="722" y="623">File Watcher</text>
<text class="node-text" x="722" y="646">scanner · chunker</text>
<text class="node-text" x="722" y="664">catalog</text>
<rect class="node" x="916" y="594" width="142" height="82" rx="14"/>
<text class="node-title" x="940" y="623">Memory</text>
<text class="node-text" x="940" y="646">FileNode</text>
<text class="node-text" x="940" y="664">FileChunk · FileLink</text>
</g>
<g class="plate" transform="translate(0,0)">
<path class="side" d="M126 818 L1074 818 L1042 848 L158 848 Z" fill="#d0b98f"/>
<rect class="plate-bg" x="126" y="738" width="948" height="108" rx="18"/>
<rect x="126" y="738" width="280" height="108" rx="18" fill="url(#workspaceGrad)"/>
<text class="layer-title" x="178" y="777">Workspace Layout</text>
<text class="layer-note" x="178" y="799">File-backed memory</text>
<g class="plate" transform="translate(0,0)">
<path class="side" d="M126 818 L1074 818 L1042 848 L158 848 Z" fill="#d0b98f"/>
<rect class="plate-bg" x="126" y="738" width="948" height="108" rx="18"/>
<rect x="126" y="738" width="280" height="108" rx="18" fill="url(#workspaceGrad)"/>
<text class="layer-title" x="178" y="777">Workspace Layout</text>
<text class="layer-note" x="178" y="799">File-backed memory</text>
<rect class="node" x="424" y="767" width="126" height="50" rx="13"/>
<text class="node-title" x="487" y="788" text-anchor="middle">daily/</text>
<text class="node-text" x="487" y="806" text-anchor="middle">working notes</text>
<rect class="node" x="584" y="767" width="126" height="50" rx="13"/>
<text class="node-title" x="647" y="788" text-anchor="middle">digest/</text>
<text class="node-text" x="647" y="806" text-anchor="middle">long-term</text>
<rect class="node" x="744" y="767" width="126" height="50" rx="13"/>
<text class="node-title" x="807" y="788" text-anchor="middle">resource/</text>
<text class="node-text" x="807" y="806" text-anchor="middle">resources</text>
<rect class="node" x="904" y="767" width="126" height="50" rx="13"/>
<text class="node-title" x="967" y="788" text-anchor="middle">metadata/</text>
<text class="node-text" x="967" y="806" text-anchor="middle">state</text>
</g>
<rect class="node" x="400" y="767" width="160" height="50" rx="13"/>
<text class="node-title" x="480" y="788" text-anchor="middle">session directories</text>
<text class="node-text" x="480" y="806" text-anchor="middle">sources · agent runtime</text>
<rect class="node" x="572" y="767" width="100" height="50" rx="13"/>
<text class="node-title" x="622" y="788" text-anchor="middle">daily/</text>
<text class="node-text" x="622" y="806" text-anchor="middle">working</text>
<rect class="node" x="684" y="767" width="100" height="50" rx="13"/>
<text class="node-title" x="734" y="788" text-anchor="middle">digest/</text>
<text class="node-text" x="734" y="806" text-anchor="middle">long-term</text>
<rect class="node" x="796" y="767" width="100" height="50" rx="13"/>
<text class="node-title" x="846" y="788" text-anchor="middle">resource/</text>
<text class="node-text" x="846" y="806" text-anchor="middle">sources</text>
<rect class="node" x="908" y="767" width="122" height="50" rx="13"/>
<text class="node-title" x="969" y="788" text-anchor="middle">metadata/</text>
<text class="node-text" x="969" y="806" text-anchor="middle">derived state</text>
</g>
<text class="section-label" x="92" y="118">EXTERNAL SURFACES</text>
<text class="section-label" x="92" y="734">PERSISTENT MEMORY BASE</text>
<text class="micro" x="600" y="878" text-anchor="middle">Structure reads bottom-up during boot and top-down during use.</text>
<text class="micro" x="600" y="896" text-anchor="middle">Workspace files feed the kernel; workflows compose operations; application wiring exposes stable service entry points.</text>
<text class="section-label" x="92" y="118">EXTERNAL SURFACES</text>
<text class="section-label" x="92" y="734">PERSISTENT MEMORY BASE</text>
<text class="micro" x="600" y="878" text-anchor="middle">Structure reads bottom-up during boot and top-down during use.</text>
<text class="micro" x="600" y="896" text-anchor="middle">Workspace files feed the kernel; workflows compose operations; application wiring exposes stable service entry points.</text>
</svg>

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 9.5 KiB

After

Width:  |  Height:  |  Size: 10 KiB

183
docs/figure/memory-as-file.svg
View file

@ -1,110 +1,97 @@
<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="670" viewBox="0 0 1200 670" role="img" aria-labelledby="title desc">
<title id="title">ReMe memory as file model</title>
<desc id="desc">A diagram showing ReMe workspace files as both a human readable memory interface and an agent operable memory graph, flowing from raw input to daily notes, digest nodes, and metadata indexes.</desc>
<defs>
<style>
.bg { fill: #fffdf8; }
.title { font: 700 30px "Comic Sans MS", "Bradley Hand", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #1f2430; }
.subtitle { font: 14px "Comic Sans MS", "Bradley Hand", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #556276; }
.section-title { font: 700 18px "Comic Sans MS", "Bradley Hand", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #1f2430; }
.section-subtitle { font: 13px "Comic Sans MS", "Bradley Hand", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #556276; }
.chip-title { font: 700 13px "Comic Sans MS", "Bradley Hand", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #1f2430; }
.chip-text { font: 12px "Comic Sans MS", "Bradley Hand", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #5e6a7c; }
.note { font: 12px "Comic Sans MS", "Bradley Hand", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #4f5c6f; }
.label { font: 700 12px "Comic Sans MS", "Bradley Hand", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #ffffff; }
.panel { fill: #ffffff; stroke: #1f2430; stroke-width: 2.2; rx: 18; ry: 18; stroke-linecap: round; stroke-linejoin: round; }
.chip { fill: #f8fbff; stroke: #1f2430; stroke-width: 1.6; rx: 11; ry: 11; stroke-linecap: round; stroke-linejoin: round; stroke-dasharray: 6 5; }
.badge { fill: #44546a; }
.soft { fill: #eef7ff; stroke: #1f2430; stroke-width: 1.6; rx: 11; ry: 11; stroke-linecap: round; stroke-linejoin: round; }
.arrow { stroke: #7f8b9d; stroke-width: 1.45; fill: none; stroke-linecap: round; stroke-linejoin: round; marker-end: url(#arrow); }
.soft-arrow { stroke: #a3adbd; stroke-width: 1.25; stroke-dasharray: 6 6; fill: none; stroke-linecap: round; stroke-linejoin: round; marker-end: url(#arrow-soft); }
.line { stroke: #a3adbd; stroke-width: 1.25; stroke-linecap: round; }
</style>
<marker id="arrow" markerWidth="6" markerHeight="6" refX="5" refY="2" orient="auto" markerUnits="strokeWidth">
<path d="M0,0 L0,4 L5,2 z" fill="#7f8b9d"/>
</marker>
<marker id="arrow-soft" markerWidth="6" markerHeight="6" refX="5" refY="2" orient="auto" markerUnits="strokeWidth">
<path d="M0,0 L0,4 L5,2 z" fill="#a3adbd"/>
</marker>
</defs>
<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="670" viewBox="0 0 1200 670" role="img"
aria-labelledby="title desc">
<title id="title">ReMe memory as file model</title>
<desc id="desc">A diagram showing ReMe workspace files as both a human readable memory interface and an agent
operable memory graph, flowing from raw input to daily notes, digest nodes, and metadata indexes.
</desc>
<defs>
<style>.bg { fill: #fffdf8; } .title { font: 700 30px "Comic Sans MS", "Bradley Hand", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #1f2430; } .subtitle { font: 14px "Comic Sans MS", "Bradley Hand", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #556276; } .section-title { font: 700 18px "Comic Sans MS", "Bradley Hand", -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif; fill: #1f2430; } .section-subtitle { font: 13px "Comic Sans MS", "Bradley Hand", -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif; fill: #556276; } .chip-title { font: 700 13px "Comic Sans MS", "Bradley Hand", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #1f2430; } .chip-text { font: 12px "Comic Sans MS", "Bradley Hand", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #5e6a7c; } .note { font: 12px "Comic Sans MS", "Bradley Hand", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #4f5c6f; } .label { font: 700 12px "Comic Sans MS", "Bradley Hand", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #ffffff; } .panel { fill: #ffffff; stroke: #1f2430; stroke-width: 2.2; rx: 18; ry: 18; stroke-linecap: round; stroke-linejoin: round; } .chip { fill: #f8fbff; stroke: #1f2430; stroke-width: 1.6; rx: 11; ry: 11; stroke-linecap: round; stroke-linejoin: round; stroke-dasharray: 6 5; } .badge { fill: #44546a; } .soft { fill: #eef7ff; stroke: #1f2430; stroke-width: 1.6; rx: 11; ry: 11; stroke-linecap: round; stroke-linejoin: round; } .arrow { stroke: #7f8b9d; stroke-width: 1.45; fill: none; stroke-linecap: round; stroke-linejoin: round; marker-end: url(#arrow); } .soft-arrow { stroke: #a3adbd; stroke-width: 1.25; stroke-dasharray: 6 6; fill: none; stroke-linecap: round; stroke-linejoin: round; marker-end: url(#arrow-soft); } .line { stroke: #a3adbd; stroke-width: 1.25; stroke-linecap: round; }</style>
<marker id="arrow" markerWidth="6" markerHeight="6" refX="5" refY="2" orient="auto" markerUnits="strokeWidth">
<path d="M0,0 L0,4 L5,2 z" fill="#7f8b9d"/>
</marker>
<marker id="arrow-soft" markerWidth="6" markerHeight="6" refX="5" refY="2" orient="auto"
markerUnits="strokeWidth">
<path d="M0,0 L0,4 L5,2 z" fill="#a3adbd"/>
</marker>
</defs>
<rect class="bg" x="0" y="0" width="1200" height="670"/>
<text class="title" x="600" y="54" text-anchor="middle">Memory as File</text>
<text class="subtitle" x="600" y="80" text-anchor="middle">Workspace files are the readable memory surface and the operable graph/index substrate.</text>
<rect class="bg" x="0" y="0" width="1200" height="670"/>
<text class="title" x="600" y="54" text-anchor="middle">Memory as File</text>
<text class="subtitle" x="600" y="80" text-anchor="middle">Workspace files are the readable memory surface and the operable graph/index substrate.</text>
<rect class="panel" x="72" y="124" width="280" height="168"/>
<rect class="badge" x="102" y="150" width="94" height="24" rx="12" ry="12"/>
<text class="label" x="149" y="167" text-anchor="middle">Human</text>
<text class="section-title" x="102" y="202">Read and edit files</text>
<text class="section-subtitle" x="102" y="226">Markdown, YAML, JSONL, resources</text>
<rect class="chip" x="102" y="248" width="220" height="28"/>
<text class="chip-text" x="212" y="267" text-anchor="middle">open, revise, move, delete</text>
<rect class="panel" x="72" y="124" width="280" height="168"/>
<rect class="badge" x="102" y="150" width="94" height="24" rx="12" ry="12"/>
<text class="label" x="149" y="167" text-anchor="middle">Human</text>
<text class="section-title" x="102" y="202">Read and edit files</text>
<text class="section-subtitle" x="102" y="226" style="font-size:11px">Markdown · YAML · JSONL · resources</text>
<rect class="chip" x="102" y="248" width="220" height="28"/>
<text class="chip-text" x="212" y="267" text-anchor="middle">open, revise, move, delete</text>
<rect class="panel" x="460" y="120" width="280" height="176"/>
<text class="section-title" x="600" y="152" text-anchor="middle">Workspace directory</text>
<text class="section-subtitle" x="600" y="176" text-anchor="middle">the shared memory interface</text>
<rect class="soft" x="504" y="204" width="192" height="30"/>
<text class="chip-title" x="600" y="224" text-anchor="middle">Memory as File</text>
<rect class="soft" x="504" y="248" width="192" height="30"/>
<text class="chip-title" x="600" y="268" text-anchor="middle">File as Memory</text>
<rect class="panel" x="460" y="120" width="280" height="176"/>
<text class="section-title" x="600" y="152" text-anchor="middle">Workspace directory</text>
<text class="section-subtitle" x="600" y="176" text-anchor="middle">the shared memory interface</text>
<rect class="soft" x="504" y="204" width="192" height="30"/>
<text class="chip-title" x="600" y="224" text-anchor="middle">Memory as File</text>
<rect class="soft" x="504" y="248" width="192" height="30"/>
<text class="chip-title" x="600" y="268" text-anchor="middle">File as Memory</text>
<rect class="panel" x="848" y="124" width="280" height="168"/>
<rect class="badge" x="878" y="150" width="94" height="24" rx="12" ry="12"/>
<text class="label" x="925" y="167" text-anchor="middle">Agent</text>
<text class="section-title" x="878" y="202">Parse and operate graph</text>
<text class="section-subtitle" x="878" y="226">frontmatter, chunks, wikilinks</text>
<rect class="chip" x="878" y="248" width="220" height="28"/>
<text class="chip-text" x="988" y="267" text-anchor="middle">search, link, rewrite, index</text>
<rect class="panel" x="848" y="124" width="280" height="168"/>
<rect class="badge" x="878" y="150" width="94" height="24" rx="12" ry="12"/>
<text class="label" x="925" y="167" text-anchor="middle">Agent</text>
<text class="section-title" x="878" y="202">Parse and operate graph</text>
<text class="section-subtitle" x="878" y="226">frontmatter, chunks, wikilinks</text>
<rect class="chip" x="878" y="248" width="220" height="28"/>
<text class="chip-text" x="988" y="267" text-anchor="middle">search, link, rewrite, index</text>
<path class="arrow" d="M352 208 H460"/>
<path class="arrow" d="M740 208 H848"/>
<path class="soft-arrow" d="M848 250 C740 326 460 326 352 250"/>
<text class="note" x="600" y="336" text-anchor="middle">people and agents see the same file tree, so edits and evidence links stay inspectable</text>
<path class="arrow" d="M352 208 H460"/>
<path class="arrow" d="M740 208 H848"/>
<path class="soft-arrow" d="M848 250 C740 326 460 326 352 250"/>
<text class="note" x="600" y="336" text-anchor="middle">people and agents see the same file tree, so edits and evidence links stay inspectable</text>
<rect class="panel" x="54" y="398" width="224" height="144"/>
<circle class="badge" cx="88" cy="432" r="15"/>
<text class="label" x="88" y="436" text-anchor="middle">1</text>
<text class="section-title" x="116" y="438">Raw input</text>
<text class="section-subtitle" x="82" y="468">keep the original scene</text>
<rect class="chip" x="82" y="494" width="168" height="28"/>
<text class="chip-text" x="166" y="513" text-anchor="middle">session/ + resource/</text>
<rect class="panel" x="54" y="398" width="224" height="144"/>
<circle class="badge" cx="88" cy="432" r="15"/>
<text class="label" x="88" y="436" text-anchor="middle">1</text>
<text class="section-title" x="116" y="438">Raw input</text>
<text class="section-subtitle" x="82" y="468">keep the original scene</text>
<rect class="chip" x="82" y="494" width="168" height="28"/>
<text class="chip-text" x="166" y="513" text-anchor="middle">session/ + resource/</text>
<rect class="panel" x="326" y="398" width="224" height="144"/>
<circle class="badge" cx="360" cy="432" r="15"/>
<text class="label" x="360" y="436" text-anchor="middle">2</text>
<text class="section-title" x="388" y="438">Daily</text>
<text class="section-subtitle" x="354" y="468">shallow working memory</text>
<rect class="chip" x="354" y="494" width="168" height="28"/>
<text class="chip-text" x="438" y="513" text-anchor="middle">daily/YYYY-MM-DD/*.md</text>
<rect class="panel" x="326" y="398" width="224" height="144"/>
<circle class="badge" cx="360" cy="432" r="15"/>
<text class="label" x="360" y="436" text-anchor="middle">2</text>
<text class="section-title" x="388" y="438">Daily</text>
<text class="section-subtitle" x="354" y="468">shallow working memory</text>
<rect class="chip" x="354" y="494" width="168" height="28"/>
<text class="chip-text" x="438" y="513" text-anchor="middle">daily/&lt;date&gt;/&lt;name&gt;.md</text>
<rect class="panel" x="598" y="398" width="224" height="144"/>
<circle class="badge" cx="632" cy="432" r="15"/>
<text class="label" x="632" y="436" text-anchor="middle">3</text>
<text class="section-title" x="660" y="438">Digest</text>
<text class="section-subtitle" x="626" y="468">long-term reusable nodes</text>
<rect class="chip" x="626" y="494" width="168" height="28"/>
<text class="chip-text" x="710" y="513" text-anchor="middle">personal / procedure / wiki</text>
<rect class="panel" x="598" y="398" width="224" height="144"/>
<circle class="badge" cx="632" cy="432" r="15"/>
<text class="label" x="632" y="436" text-anchor="middle">3</text>
<text class="section-title" x="660" y="438">Digest</text>
<text class="section-subtitle" x="626" y="468">long-term reusable nodes</text>
<rect class="chip" x="626" y="494" width="168" height="28"/>
<text class="chip-text" x="710" y="513" text-anchor="middle">personal / procedure / wiki</text>
<rect class="panel" x="870" y="398" width="224" height="144"/>
<circle class="badge" cx="904" cy="432" r="15"/>
<text class="label" x="904" y="436" text-anchor="middle">4</text>
<text class="section-title" x="932" y="438">Metadata</text>
<text class="section-subtitle" x="898" y="468">system state and indexes</text>
<rect class="chip" x="898" y="494" width="168" height="28"/>
<text class="chip-text" x="982" y="513" text-anchor="middle">catalog + chunks + links</text>
<rect class="panel" x="870" y="398" width="224" height="144"/>
<circle class="badge" cx="904" cy="432" r="15"/>
<text class="label" x="904" y="436" text-anchor="middle">4</text>
<text class="section-title" x="932" y="438">Metadata</text>
<text class="section-subtitle" x="898" y="468">system state and indexes</text>
<rect class="chip" x="898" y="494" width="168" height="28"/>
<text class="chip-text" x="982" y="513" text-anchor="middle">catalog + chunks + links</text>
<path class="arrow" d="M278 470 H326"/>
<path class="arrow" d="M550 470 H598"/>
<path class="arrow" d="M822 470 H870"/>
<path class="soft-arrow" d="M982 398 C982 356 710 356 710 398"/>
<path class="soft-arrow" d="M982 542 C982 592 438 592 438 542"/>
<path class="arrow" d="M278 470 H326"/>
<path class="arrow" d="M550 470 H598"/>
<path class="arrow" d="M822 470 H870"/>
<path class="soft-arrow" d="M982 398 C982 356 710 356 710 398"/>
<path class="soft-arrow" d="M982 542 C982 592 438 592 438 542"/>
<rect class="panel" x="126" y="594" width="948" height="46"/>
<text class="note" x="176" y="622">Stable paths</text>
<line class="line" x1="308" y1="606" x2="308" y2="628"/>
<text class="chip-text" x="360" y="622">workspace-relative wikilinks</text>
<line class="line" x1="548" y1="606" x2="548" y2="628"/>
<text class="chip-text" x="600" y="622">derived_from evidence edges</text>
<line class="line" x1="814" y1="606" x2="814" y2="628"/>
<text class="chip-text" x="862" y="622">search expands structure and links</text>
<rect class="panel" x="126" y="594" width="948" height="46"/>
<text class="note" x="176" y="622">Stable paths</text>
<line class="line" x1="308" y1="606" x2="308" y2="628"/>
<text class="chip-text" x="360" y="622">workspace-relative wikilinks</text>
<line class="line" x1="548" y1="606" x2="548" y2="628"/>
<text class="chip-text" x="600" y="622">derived_from evidence edges</text>
<line class="line" x1="814" y1="606" x2="814" y2="628"/>
<text class="chip-text" x="862" y="622">search expands linked context</text>
</svg>

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 7.6 KiB

After

Width:  |  Height:  |  Size: 7.7 KiB

121
docs/figure/reme-blog/reme-blog-architecture.svg
View file

File diff suppressed because one or more lines are too long
Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 47 KiB

After

Width:  |  Height:  |  Size: 47 KiB

170
docs/figure/reme-blog/reme-blog-auto-dream.svg
View file

File diff suppressed because one or more lines are too long
Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 384 KiB

After

Width:  |  Height:  |  Size: 385 KiB

84
docs/figure/reme-blog/reme-blog-auto-memory.svg
View file

File diff suppressed because one or more lines are too long
Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 46 KiB

After

Width:  |  Height:  |  Size: 46 KiB

138
docs/figure/reme-blog/reme-blog-auto-resource.svg
View file

@ -1,80 +1,80 @@
<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="640" viewBox="0 0 1200 640" role="img" aria-labelledby="title desc">
<title id="title">Auto Resource</title>
<desc id="desc">A general workflow that imports external information, interprets it with traceable sources, and integrates it into a user-owned personal knowledge base.</desc>
<defs>
<style>
.bg{fill:#fffdf8}.title{font:800 30px Arial,sans-serif;fill:#1f2430}.sub{font:14px Arial,sans-serif;fill:#667085}.panel{fill:#fff;stroke:#1f2430;stroke-width:2}.head{font:700 18px Arial,sans-serif;fill:#1f2430}.text{font:13px Arial,sans-serif;fill:#5e6a7c}.small{font:12px Arial,sans-serif;fill:#667085}.label{font:700 13px Arial,sans-serif;fill:#1f2430}.path{font:700 13px Arial,sans-serif;fill:#e66f11}.chip{fill:#f8fbff;stroke:#1f2430;stroke-width:1.3;stroke-dasharray:6 5}.orange{fill:#fff3e7}.blue{fill:#eef7ff}.green{fill:#eef9f4}.arrow{fill:none;stroke:#8793a3;stroke-width:2.5;marker-end:url(#a)}
</style>
<marker id="a" markerWidth="9" markerHeight="9" refX="8" refY="4.5" orient="auto">
<path d="M0 0v9l9-4.5z" fill="#8793a3"/>
</marker>
</defs>
<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="640" viewBox="0 0 1200 640" role="img"
aria-labelledby="title desc">
<title id="title">Auto Resource</title>
<desc id="desc">A general workflow that imports external information, interprets it with traceable sources, and
integrates it into a user-owned personal knowledge base.
</desc>
<defs>
<style>.bg{fill:#fffdf8}.title{font:800 30px Arial,sans-serif;fill:#1f2430}.sub{font:14px Arial,sans-serif;fill:#667085}.panel{fill:#fff;stroke:#1f2430;stroke-width:2}.head{font:700 18px Arial,sans-serif;fill:#1f2430}.text{font:13px Arial,sans-serif;fill:#5e6a7c}.small{font:12px Arial,sans-serif;fill:#667085}.label{font:700 13px Arial,sans-serif;fill:#1f2430}.path{font:700 13px Arial,sans-serif;fill:#e66f11}.chip{fill:#f8fbff;stroke:#1f2430;stroke-width:1.3;stroke-dasharray:6 5}.orange{fill:#fff3e7}.blue{fill:#eef7ff}.green{fill:#eef9f4}.arrow{fill:none;stroke:#8793a3;stroke-width:2.5;marker-end:url(#a)}</style>
<marker id="a" markerWidth="9" markerHeight="9" refX="8" refY="4.5" orient="auto">
<path d="M0 0v9l9-4.5z" fill="#8793a3"/>
</marker>
</defs>
<rect class="bg" width="1200" height="640"/>
<text class="title" x="600" y="50" text-anchor="middle">Auto Resource</text>
<text class="sub" x="600" y="77" text-anchor="middle">Bring external information into a traceable, user-owned knowledge base</text>
<text x="1080" y="51" style="font:800 25px Arial,sans-serif;fill:#19bfc3">Re</text>
<text x="1111" y="51" style="font:800 25px Arial,sans-serif;fill:#3274d9">Me</text>
<rect class="bg" width="1200" height="640"/>
<text text-anchor="middle"><tspan class="title" x="600" y="50">Auto Resource</tspan><tspan class="sub" x="600" y="77">Bring external information into a traceable, user-owned knowledge base</tspan></text>
<text x="1080" y="51" style="font:800 25px Arial,sans-serif;fill:#19bfc3">Re</text>
<text x="1111" y="51" style="font:800 25px Arial,sans-serif;fill:#3274d9">Me</text>
<rect class="panel" x="46" y="112" width="304" height="458" rx="18"/>
<circle cx="92" cy="159" r="24" fill="#ff963d"/>
<path d="M80 149h21l7 7v19H80z" fill="#fff"/>
<path d="M101 149v8h8" fill="none" stroke="#ff963d" stroke-width="2"/>
<text class="head" x="128" y="155">External Information</text>
<text class="text" x="128" y="179">Keep originals as the source of truth</text>
<rect class="panel" x="46" y="112" width="304" height="458" rx="18"/>
<circle cx="92" cy="159" r="24" fill="#ff963d"/>
<path d="M80 149h21l7 7v19H80z" fill="#fff"/>
<path d="M101 149v8h8" fill="none" stroke="#ff963d" stroke-width="2"/>
<text class="head" x="128" y="155">External Information</text>
<text class="text" x="128" y="179" style="font-size:13px">Originals remain verifiable</text>
<rect class="chip orange" x="76" y="214" width="244" height="68" rx="11"/>
<text class="label" x="198" y="240" text-anchor="middle">Documents · notes · web archives</text>
<text class="small" x="198" y="263" text-anchor="middle">research · reports · structured data</text>
<rect class="chip" x="76" y="302" width="244" height="68" rx="11"/>
<text class="label" x="198" y="328" text-anchor="middle">md · txt · json · jsonl</text>
<text class="small" x="198" y="351" text-anchor="middle">csv · yaml · html</text>
<rect class="chip" x="76" y="390" width="244" height="68" rx="11"/>
<text class="label" x="198" y="416" text-anchor="middle">Create · update · delete</text>
<text class="small" x="198" y="439" text-anchor="middle">Changes remain visible and recoverable</text>
<text class="path" x="198" y="505" text-anchor="middle">resource/</text>
<text class="text" x="198" y="532" text-anchor="middle">Original files remain user-owned</text>
<rect class="chip orange" x="76" y="214" width="244" height="68" rx="11"/>
<text class="label" x="198" y="240" text-anchor="middle">Documents · notes · web archives</text>
<text class="small" x="198" y="263" text-anchor="middle">research · reports · structured data</text>
<rect class="chip" x="76" y="302" width="244" height="68" rx="11"/>
<text class="label" x="198" y="328" text-anchor="middle">md · txt · json · jsonl</text>
<text class="small" x="198" y="351" text-anchor="middle">csv · yaml · html</text>
<rect class="chip" x="76" y="390" width="244" height="68" rx="11"/>
<text class="label" x="198" y="416" text-anchor="middle">Create · update · delete</text>
<text class="small" x="198" y="439" text-anchor="middle" style="font-size:12px">Changes stay visible and recoverable</text>
<text class="path" x="198" y="505" text-anchor="middle">resource/</text>
<text class="text" x="198" y="532" text-anchor="middle">Original files remain user-owned</text>
<path class="arrow" d="M350 341h62"/>
<path class="arrow" d="M350 341h62"/>
<rect class="panel" x="412" y="112" width="376" height="458" rx="18"/>
<circle cx="458" cy="159" r="24" fill="#5b91dc"/>
<path d="M445 149h26v22h-26zM451 143h14v6" fill="#fff" stroke="#fff" stroke-width="3" stroke-linejoin="round"/>
<text class="head" x="494" y="155">Auto Resource Ingestion</text>
<text class="text" x="494" y="179">Parse, interpret, and preserve provenance</text>
<rect class="panel" x="412" y="112" width="376" height="458" rx="18"/>
<circle cx="458" cy="159" r="24" fill="#5b91dc"/>
<path d="M445 149h26v22h-26zM451 143h14v6" fill="#fff" stroke="#fff" stroke-width="3" stroke-linejoin="round"/>
<text class="head" x="494" y="155">Auto Resource Ingestion</text>
<text class="text" x="494" y="179">Parse, interpret, and preserve provenance</text>
<rect class="chip blue" x="442" y="214" width="316" height="68" rx="11"/>
<text class="label" x="468" y="240">1 Parse content and structure</text>
<text class="small" x="468" y="263">Read text, sections, fields, and metadata</text>
<rect class="chip orange" x="442" y="302" width="316" height="68" rx="11"/>
<text class="label" x="468" y="328">2 Interpret reusable information</text>
<text class="small" x="468" y="351">Extract themes, key facts, and actionable details</text>
<rect class="chip green" x="442" y="390" width="316" height="68" rx="11"/>
<text class="label" x="468" y="416">3 Attach traceable provenance</text>
<text class="small" x="468" y="439">Link every memory back with source_resource</text>
<text class="path" x="600" y="505" text-anchor="middle">daily/</text>
<text class="text" x="600" y="532" text-anchor="middle">Write readable resource memory</text>
<rect class="chip blue" x="442" y="214" width="316" height="68" rx="11"/>
<text class="label" x="468" y="240">1 Parse content and structure</text>
<text class="small" x="468" y="263">Read text, sections, fields, and metadata</text>
<rect class="chip orange" x="442" y="302" width="316" height="68" rx="11"/>
<text class="label" x="468" y="328">2 Interpret reusable information</text>
<text class="small" x="468" y="351" style="font-size:12px">Extract themes, facts, and actionable details</text>
<rect class="chip green" x="442" y="390" width="316" height="68" rx="11"/>
<text class="label" x="468" y="416">3 Attach traceable provenance</text>
<text class="small" x="468" y="439" style="font-size:12px">Link each memory with source_resource</text>
<text class="path" x="600" y="505" text-anchor="middle">daily/</text>
<text class="text" x="600" y="532" text-anchor="middle">Write readable resource memory</text>
<path class="arrow" d="M788 341h62"/>
<path class="arrow" d="M788 341h62"/>
<rect class="panel" x="850" y="112" width="304" height="458" rx="18"/>
<circle cx="896" cy="159" r="24" fill="#ff963d"/>
<path d="M883 171c7-19 18-26 27-27-1 12-6 25-27 27z" fill="#fff"/>
<path d="M896 151v23" stroke="#fff" stroke-width="3" stroke-linecap="round"/>
<text class="head" x="932" y="155">Knowledge Base</text>
<text class="text" x="932" y="179">One memory system for every source</text>
<rect class="panel" x="850" y="112" width="304" height="458" rx="18"/>
<circle cx="896" cy="159" r="24" fill="#ff963d"/>
<path d="M883 171c7-19 18-26 27-27-1 12-6 25-27 27z" fill="#fff"/>
<path d="M896 151v23" stroke="#fff" stroke-width="3" stroke-linecap="round"/>
<text class="head" x="932" y="155">Knowledge Base</text>
<text class="text" x="932" y="179" style="font-size:13px">One memory system per source</text>
<rect class="chip blue" x="880" y="214" width="244" height="68" rx="11"/>
<text class="label" x="1002" y="240" text-anchor="middle">daily/</text>
<text class="small" x="1002" y="263" text-anchor="middle">Readable, traceable resource memory</text>
<rect class="chip green" x="880" y="302" width="244" height="68" rx="11"/>
<text class="label" x="1002" y="328" text-anchor="middle">digest/</text>
<text class="small" x="1002" y="351" text-anchor="middle">Long-term knowledge via Auto Dream</text>
<rect class="chip" x="880" y="390" width="244" height="68" rx="11"/>
<text class="label" x="1002" y="416" text-anchor="middle">metadata/</text>
<text class="small" x="1002" y="439" text-anchor="middle">Rebuildable index and knowledge graph</text>
<text class="path" x="1002" y="505" text-anchor="middle">Search · link · reuse</text>
<text class="text" x="1002" y="532" text-anchor="middle">External knowledge returns to future tasks</text>
<rect class="chip blue" x="880" y="214" width="244" height="68" rx="11"/>
<text class="label" x="1002" y="240" text-anchor="middle">daily/</text>
<text class="small" x="1002" y="263" text-anchor="middle" style="font-size:12px">Readable, traceable resource memory</text>
<rect class="chip green" x="880" y="302" width="244" height="68" rx="11"/>
<text class="label" x="1002" y="328" text-anchor="middle">digest/</text>
<text class="small" x="1002" y="351" text-anchor="middle" style="font-size:12px">Long-term memory via Auto Dream</text>
<rect class="chip" x="880" y="390" width="244" height="68" rx="11"/>
<text class="label" x="1002" y="416" text-anchor="middle">metadata/</text>
<text class="small" x="1002" y="439" text-anchor="middle" style="font-size:12px">Rebuildable index and link graph</text>
<text class="path" x="1002" y="505" text-anchor="middle">Search · link · reuse</text>
<text class="text" x="1002" y="532" text-anchor="middle">External knowledge returns to future tasks</text>
<text class="small" x="600" y="610" text-anchor="middle">User files stay authoritative · derived indexes remain rebuildable</text>
<text class="small" x="600" y="610" text-anchor="middle">User files stay authoritative · derived indexes remain rebuildable</text>
</svg>

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 5.7 KiB

After

Width:  |  Height:  |  Size: 6 KiB

75
docs/figure/reme-blog/reme-blog-cover-benchmark.svg
View file

@ -1,47 +1,44 @@
<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="1680" height="973" viewBox="0 0 1680 973" role="img" aria-labelledby="title desc">
<title id="title">ReMe Hero and Public Benchmark Results</title>
<desc id="desc">ReMe self-evolving personal knowledge base hero with LongMemEval 89.4%, BEAM 100K 66.1%, and BEAM 1M 65.0% results.</desc>
<defs>
<linearGradient id="glass" x1="0" y1="0" x2="1" y2="0">
<stop offset="0" stop-color="#171b25" stop-opacity="0.96"/>
<stop offset="0.58" stop-color="#202530" stop-opacity="0.94"/>
<stop offset="1" stop-color="#252b36" stop-opacity="0.92"/>
</linearGradient>
<filter id="shadow" x="-20%" y="-30%" width="140%" height="180%">
<feDropShadow dx="0" dy="-8" stdDeviation="16" flood-color="#000" flood-opacity="0.16"/>
</filter>
<style>
.sans{font-family:Arial,sans-serif}
.eyebrow{font-size:17px;font-weight:750;letter-spacing:2px;fill:#ffad61}
.metric{font-size:49px;font-weight:900;letter-spacing:-1.5px;fill:#fff}
.label{font-size:17px;font-weight:720;fill:#fff}
.small{font-size:14px;font-weight:520;fill:#d0d5dd}
</style>
</defs>
<image xlink:href="reme-blog-cover.png" x="0" y="0" width="1680" height="973" preserveAspectRatio="xMidYMid slice"/>
<rect x="0" y="711" width="1680" height="262" fill="url(#glass)" filter="url(#shadow)"/>
<g class="sans">
<text class="eyebrow" x="84" y="765">PUBLIC BENCHMARK RESULTS</text>
<text class="small" x="84" y="798">Agentic scores across multi-session and long-context settings</text>
<svg xmlns:xlink="http://www.w3.org/1999/xlink" xmlns="http://www.w3.org/2000/svg" width="1680" height="973"
viewBox="0 0 1680 973" role="img" aria-labelledby="title desc">
<title id="title">ReMe Hero and Public Benchmark Results</title>
<desc id="desc">ReMe self-evolving personal knowledge base hero with LongMemEval 89.4%, BEAM 100K 66.1%, and BEAM 1M
65.0% results.
</desc>
<defs>
<linearGradient id="glass" x1="0" y1="0" x2="1" y2="0">
<stop offset="0" stop-color="#171b25" stop-opacity="0.96"/>
<stop offset="0.58" stop-color="#202530" stop-opacity="0.94"/>
<stop offset="1" stop-color="#252b36" stop-opacity="0.92"/>
</linearGradient>
<filter id="shadow" x="-20%" y="-30%" width="140%" height="180%">
<feDropShadow dx="0" dy="-8" stdDeviation="16" flood-color="#000" flood-opacity="0.16"/>
</filter>
<style>.sans{font-family:Arial,sans-serif} .eyebrow{font-size:17px;font-weight:750;letter-spacing:2px;fill:#ffad61} .metric{font-size:49px;font-weight:900;letter-spacing:-1.5px;fill:#fff} .label{font-size:17px;font-weight:720;fill:#fff} .small{font-size:14px;font-weight:520;fill:#d0d5dd}</style>
</defs>
<image xlink:href="reme-blog-cover.png" x="0" y="0" width="1680" height="973" preserveAspectRatio="xMidYMid slice"/>
<rect x="0" y="711" width="1680" height="262" fill="url(#glass)" filter="url(#shadow)"/>
<g class="sans">
<text class="eyebrow" x="84" y="765">PUBLIC BENCHMARK RESULTS</text>
<text class="small" x="84" y="798">Agentic scores across multi-session and long-context settings</text>
<line x1="84" y1="829" x2="1596" y2="829" stroke="#fff" stroke-opacity="0.17"/>
<line x1="84" y1="829" x2="1596" y2="829" stroke="#fff" stroke-opacity="0.17"/>
<text class="metric" x="84" y="898">89.4%</text>
<text class="label" x="277" y="875">LongMemEval cleaned-s</text>
<text class="small" x="277" y="903">500 questions · cross-session retrieval</text>
<text class="metric" x="84" y="898">89.4%</text>
<text class="label" x="277" y="875">LongMemEval cleaned-s</text>
<text class="small" x="277" y="903">500 questions · cross-session retrieval</text>
<line x1="590" y1="852" x2="590" y2="923" stroke="#fff" stroke-opacity="0.18"/>
<line x1="590" y1="852" x2="590" y2="923" stroke="#fff" stroke-opacity="0.18"/>
<text class="metric" x="650" y="898">66.1%</text>
<text class="label" x="833" y="875">BEAM 100K</text>
<text class="small" x="833" y="903">20 cases · 400 questions</text>
<text class="metric" x="650" y="898">66.1%</text>
<text class="label" x="833" y="875">BEAM 100K</text>
<text class="small" x="833" y="903">20 cases · 400 questions</text>
<line x1="1080" y1="852" x2="1080" y2="923" stroke="#fff" stroke-opacity="0.18"/>
<line x1="1080" y1="852" x2="1080" y2="923" stroke="#fff" stroke-opacity="0.18"/>
<text class="metric" x="1140" y="898">65.0%</text>
<text class="label" x="1323" y="875">BEAM 1M</text>
<text class="small" x="1323" y="903">35 cases · 700 questions</text>
<text class="metric" x="1140" y="898">65.0%</text>
<text class="label" x="1323" y="875">BEAM 1M</text>
<text class="small" x="1323" y="903">35 cases · 700 questions</text>
<text x="1596" y="950" text-anchor="end" style="font-size:12px;font-weight:520;fill:#98a2b3">Scores from different benchmarks are not compared directly</text>
</g>
<text x="1596" y="950" text-anchor="end" style="font-size:12px;font-weight:520;fill:#98a2b3">Scores from different benchmarks are not compared directly</text>
</g>
</svg>

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 2.6 KiB

After

Width:  |  Height:  |  Size: 2.7 KiB

21
docs/figure/reme-blog/reme-blog-memory-as-file.svg
View file

@ -6,20 +6,7 @@
<stop offset="0%" stop-color="#3568B8"/>
<stop offset="100%" stop-color="#2A9D8F"/>
</linearGradient>
<style>
.bg { fill: #fffdf8; }
.title { font: 800 30px Arial, sans-serif; fill: #1f2430; }
.sub { font: 14px Arial, sans-serif; fill: #667085; }
.panel { fill: #fff; stroke: #365A73; stroke-width: 2; }
.top { fill: url(#headerGradient); }
.white { font: 14px ui-monospace, SFMono-Regular, Menlo, monospace; fill: #fff; }
.mono { font: 14px ui-monospace, SFMono-Regular, Menlo, monospace; fill: #283342; }
.folder { font: 700 15px ui-monospace, SFMono-Regular, Menlo, monospace; fill: #1767b1; }
.head { font: 700 17px Arial, sans-serif; fill: #1f2430; }
.text { font: 13px Arial, sans-serif; fill: #5e6a7c; }
.link { fill: none; stroke: #ff963d; stroke-width: 2.5; }
.dot { fill: #ff963d; }
</style>
<style>.bg { fill: #fffdf8; } .title { font: 800 30px Arial, sans-serif; fill: #1f2430; } .sub { font: 14px Arial, sans-serif; fill: #667085; } .panel { fill: #fff; stroke: #365A73; stroke-width: 2; } .top { fill: url(#headerGradient); } .white { font: 14px ui-monospace, SFMono-Regular, Menlo, monospace; fill: #fff; } .mono { font: 14px ui-monospace, SFMono-Regular, Menlo, monospace; fill: #283342; } .folder { font: 700 15px ui-monospace, SFMono-Regular, Menlo, monospace; fill: #1767b1; } .head { font: 700 17px Arial, sans-serif; fill: #1f2430; } .text { font: 13px Arial, sans-serif; fill: #5e6a7c; } .link { fill: none; stroke: #ff963d; stroke-width: 2.5; } .dot { fill: #ff963d; }</style>
</defs>
<rect class="bg" width="1200" height="640"/>
@ -37,9 +24,9 @@
<text class="head" x="90" y="358">Lead with the problem and outcome.</text>
<text class="text" x="90" y="386">Use examples; explain technical details without jargon.</text>
<text class="mono" x="90" y="434">Related:</text>
<text class="folder" x="170" y="434">[[technical-writing-workflow]]</text>
<text class="folder" x="170" y="434">[[digest/procedure/writing.md]]</text>
<text class="mono" x="90" y="480">Source:</text>
<text class="folder" x="170" y="480">[[daily/2026-08-07]]</text>
<text class="folder" x="170" y="480">[[daily/2026-08-07/style.md]]</text>
<path class="link" d="M594 426C635 426 640 350 680 350"/>
<path class="link" d="M594 472C635 472 640 308 680 308"/>
@ -50,7 +37,7 @@
<path class="top" d="M698 116h430a18 18 0 0118 18v48H680v-48a18 18 0 0118-18z"/>
<text class="white" x="714" y="158">workspace/</text>
<text class="folder" x="716" y="224">├── session/</text>
<text class="text" x="900" y="224">Raw conversations</text>
<text class="text" x="900" y="224">Source conversations</text>
<text class="folder" x="716" y="266">├── resource/</text>
<text class="text" x="900" y="266">External resources</text>
<text class="folder" x="716" y="308">├── daily/</text>

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 382 KiB

After

Width:  |  Height:  |  Size: 382 KiB

100
docs/figure/reme-blog/reme-blog-memory-index.svg
View file

File diff suppressed because one or more lines are too long
Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 46 KiB

After

Width:  |  Height:  |  Size: 46 KiB

87
docs/figure/reme-blog/reme-blog-memory-search.svg
View file

File diff suppressed because one or more lines are too long
Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 46 KiB

After

Width:  |  Height:  |  Size: 46 KiB

92
docs/figure/reme-blog/reme-blog-proactive.svg
View file

File diff suppressed because one or more lines are too long
Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 47 KiB

After

Width:  |  Height:  |  Size: 47 KiB

334
docs/figure/reme-overview.svg
View file

@ -1,204 +1,184 @@
<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="640" viewBox="0 0 1200 640" role="img" aria-labelledby="title desc">
<title id="title">ReMe overview</title>
<desc id="desc">A hand-drawn style overview of ReMe, showing Auto Memory plus Auto Resource, Auto Dream plus Proactive, Auto Index plus Memory Search, and Memory as File.</desc>
<defs>
<style>
.bg { fill: #fffdf8; }
.ink { stroke: #1f2430; stroke-width: 2.2; stroke-linecap: round; stroke-linejoin: round; }
.thin { stroke-width: 1.6; }
.dash { stroke-dasharray: 8 7; }
.title { font: 700 30px "Comic Sans MS", "Bradley Hand", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #1f2430; }
.subtitle { font: 14px "Comic Sans MS", "Bradley Hand", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #556276; }
.head { font: 700 17px "Comic Sans MS", "Bradley Hand", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #1f2430; }
.label { font: 700 13px "Comic Sans MS", "Bradley Hand", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #1f2430; }
.text { font: 12px "Comic Sans MS", "Bradley Hand", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #4f5c6f; }
.tiny { font: 11px "Comic Sans MS", "Bradley Hand", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #5e6a7c; }
.box { fill: #ffffff; }
.blue { fill: #eef7ff; }
.green { fill: #f0fbf5; }
.yellow { fill: #fff7e5; }
.pink { fill: #fff2f6; }
.violet { fill: #f4f1ff; }
.mint { fill: #eefafa; }
.peach { fill: #fff2ea; }
.paper { fill: #f8fbff; }
.tab { fill: #ffffff; }
.step { stroke-dasharray: 6 5; }
.arrow { fill: none; stroke: #7f8b9d; stroke-width: 1.45; stroke-linecap: round; stroke-linejoin: round; marker-end: url(#arrow); }
.soft-arrow { fill: none; stroke: #a3adbd; stroke-width: 1.25; stroke-dasharray: 6 6; stroke-linecap: round; stroke-linejoin: round; marker-end: url(#arrow-soft); }
</style>
<marker id="arrow" markerWidth="6" markerHeight="6" refX="5" refY="2" orient="auto" markerUnits="strokeWidth">
<path d="M0,0 L0,4 L5,2 z" fill="#7f8b9d"/>
</marker>
<marker id="arrow-soft" markerWidth="6" markerHeight="6" refX="5" refY="2" orient="auto" markerUnits="strokeWidth">
<path d="M0,0 L0,4 L5,2 z" fill="#a3adbd"/>
</marker>
</defs>
<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="640" viewBox="0 0 1200 640" role="img"
aria-labelledby="title desc">
<title id="title">ReMe overview</title>
<desc id="desc">A hand-drawn style overview of ReMe, showing Auto Memory plus Auto Resource, Auto Dream plus
Proactive, Auto Index plus Memory Search, and Memory as File.
</desc>
<defs>
<style>.bg { fill: #fffdf8; } .ink { stroke: #1f2430; stroke-width: 2.2; stroke-linecap: round; stroke-linejoin: round; } .thin { stroke-width: 1.6; } .dash { stroke-dasharray: 8 7; } .title { font: 700 30px "Comic Sans MS", "Bradley Hand", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #1f2430; } .subtitle { font: 14px "Comic Sans MS", "Bradley Hand", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #556276; } .head { font: 700 17px "Comic Sans MS", "Bradley Hand", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #1f2430; } .label { font: 700 13px "Comic Sans MS", "Bradley Hand", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #1f2430; } .text { font: 12px "Comic Sans MS", "Bradley Hand", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #4f5c6f; } .tiny { font: 11px "Comic Sans MS", "Bradley Hand", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #5e6a7c; } .box { fill: #ffffff; } .blue { fill: #eef7ff; } .green { fill: #f0fbf5; } .yellow { fill: #fff7e5; } .pink { fill: #fff2f6; } .violet { fill: #f4f1ff; } .mint { fill: #eefafa; } .peach { fill: #fff2ea; } .paper { fill: #f8fbff; } .tab { fill: #ffffff; } .step { stroke-dasharray: 6 5; } .arrow { fill: none; stroke: #7f8b9d; stroke-width: 1.45; stroke-linecap: round; stroke-linejoin: round; marker-end: url(#arrow); } .soft-arrow { fill: none; stroke: #a3adbd; stroke-width: 1.25; stroke-dasharray: 6 6; stroke-linecap: round; stroke-linejoin: round; marker-end: url(#arrow-soft); }</style>
<marker id="arrow" markerWidth="6" markerHeight="6" refX="5" refY="2" orient="auto" markerUnits="strokeWidth">
<path d="M0,0 L0,4 L5,2 z" fill="#7f8b9d"/>
</marker>
<marker id="arrow-soft" markerWidth="6" markerHeight="6" refX="5" refY="2" orient="auto"
markerUnits="strokeWidth">
<path d="M0,0 L0,4 L5,2 z" fill="#a3adbd"/>
</marker>
</defs>
<rect class="bg" x="0" y="0" width="1200" height="640"/>
<text class="title" x="600" y="44" text-anchor="middle">ReMe</text>
<text class="subtitle" x="600" y="68" text-anchor="middle">A file-native memory loop: capture, consolidate, link, search, and proactively surface what matters.</text>
<rect class="bg" x="0" y="0" width="1200" height="640"/>
<text class="title" x="600" y="44" text-anchor="middle">ReMe</text>
<text class="subtitle" x="600" y="68" text-anchor="middle">A file-native memory loop: capture, consolidate, link, search, and proactively surface what matters.</text>
<!-- Top workflow -->
<g transform="translate(40 120)">
<rect class="blue ink thin" x="0" y="0" width="300" height="260" rx="18"/>
<text class="head" x="150" y="31" text-anchor="middle">Auto Memory + Auto Resource</text>
<text class="text" x="150" y="56" text-anchor="middle">Capture sessions and resources into daily cards.</text>
<!-- Top workflow -->
<g transform="translate(40 120)">
<rect class="blue ink thin" x="0" y="0" width="300" height="260" rx="18"/>
<text class="head" x="150" y="31" text-anchor="middle">Auto Memory + Auto Resource</text>
<text class="text" x="150" y="56" text-anchor="middle" style="font-size:12px">Capture sessions and resources into daily cards.</text>
<g transform="translate(24 78)">
<rect class="blue ink thin dash" x="0" y="0" width="252" height="64" rx="13"/>
<text class="label" x="54" y="27" text-anchor="middle">Auto</text>
<text class="label" x="54" y="45" text-anchor="middle">Memory</text>
<g transform="translate(24 78)">
<rect class="blue ink thin dash" x="0" y="0" width="252" height="64" rx="13"/>
<text class="label" x="54" y="27" text-anchor="middle">Auto</text>
<text class="label" x="54" y="45" text-anchor="middle">Memory</text>
<rect class="box ink thin step" x="100" y="12" width="62" height="40" rx="9"/>
<text class="label" x="131" y="29" text-anchor="middle">Capture</text>
<text class="tiny" x="131" y="44" text-anchor="middle">chat</text>
<rect class="box ink thin step" x="100" y="12" width="62" height="40" rx="9"/>
<text class="label" x="131" y="29" text-anchor="middle">Capture</text>
<text class="tiny" x="131" y="44" text-anchor="middle">chat</text>
<rect class="yellow ink thin step" x="178" y="12" width="56" height="40" rx="9"/>
<text class="label" x="206" y="29" text-anchor="middle">Write</text>
<text class="tiny" x="206" y="44" text-anchor="middle">daily</text>
<rect class="yellow ink thin step" x="178" y="12" width="56" height="40" rx="9"/>
<text class="label" x="206" y="29" text-anchor="middle">Write</text>
<text class="tiny" x="206" y="44" text-anchor="middle">daily</text>
<path class="arrow" d="M164 32 H176"/>
<path class="arrow" d="M164 32 H176"/>
</g>
<g transform="translate(24 162)">
<rect class="green ink thin dash" x="0" y="0" width="252" height="64" rx="13"/>
<text class="label" x="54" y="27" text-anchor="middle">Auto</text>
<text class="label" x="54" y="45" text-anchor="middle">Resource</text>
<rect class="box ink thin step" x="100" y="12" width="62" height="40" rx="9"/>
<text class="label" x="131" y="29" text-anchor="middle">Read</text>
<text class="tiny" x="131" y="44" text-anchor="middle">source</text>
<rect class="yellow ink thin step" x="178" y="12" width="56" height="40" rx="9"/>
<text class="label" x="206" y="29" text-anchor="middle">Write</text>
<text class="tiny" x="206" y="44" text-anchor="middle">daily</text>
<path class="arrow" d="M164 32 H176"/>
</g>
</g>
<g transform="translate(24 162)">
<rect class="green ink thin dash" x="0" y="0" width="252" height="64" rx="13"/>
<text class="label" x="54" y="27" text-anchor="middle">Auto</text>
<text class="label" x="54" y="45" text-anchor="middle">Resource</text>
<g transform="translate(380 120)">
<rect class="yellow ink thin" x="0" y="0" width="320" height="260" rx="18"/>
<text class="head" x="160" y="32" text-anchor="middle">Auto Dream + Proactive</text>
<text class="text" x="160" y="58" text-anchor="middle" style="font-size:12px">Consolidate notes, link knowledge, surface interests.</text>
<rect class="box ink thin step" x="100" y="12" width="62" height="40" rx="9"/>
<text class="label" x="131" y="29" text-anchor="middle">Read</text>
<text class="tiny" x="131" y="44" text-anchor="middle">source</text>
<rect class="box ink thin step" x="38" y="84" width="112" height="56" rx="12"/>
<text class="label" x="94" y="108" text-anchor="middle">Extract</text>
<text class="tiny" x="94" y="126" text-anchor="middle">changed files</text>
<rect class="yellow ink thin step" x="178" y="12" width="56" height="40" rx="9"/>
<text class="label" x="206" y="29" text-anchor="middle">Write</text>
<text class="tiny" x="206" y="44" text-anchor="middle">daily</text>
<rect class="peach ink thin step" x="170" y="84" width="112" height="56" rx="12"/>
<text class="label" x="226" y="108" text-anchor="middle">Auto Link</text>
<text class="tiny" x="226" y="126" text-anchor="middle">dedupe + edges</text>
<path class="arrow" d="M164 32 H176"/>
</g>
</g>
<rect class="pink ink thin step" x="38" y="168" width="112" height="56" rx="12"/>
<text class="label" x="94" y="192" text-anchor="middle">Integrate</text>
<text class="tiny" x="94" y="210" text-anchor="middle">write digest</text>
<g transform="translate(380 120)">
<rect class="yellow ink thin" x="0" y="0" width="320" height="260" rx="18"/>
<text class="head" x="160" y="32" text-anchor="middle">Auto Dream + Proactive</text>
<text class="text" x="160" y="58" text-anchor="middle">Consolidate notes, link knowledge, surface interests.</text>
<rect class="mint ink thin step" x="170" y="168" width="112" height="56" rx="12"/>
<text class="label" x="226" y="192" text-anchor="middle">Proactive</text>
<text class="tiny" x="226" y="210" text-anchor="middle">interests.yaml</text>
<rect class="box ink thin step" x="38" y="84" width="112" height="56" rx="12"/>
<text class="label" x="94" y="108" text-anchor="middle">Extract</text>
<text class="tiny" x="94" y="126" text-anchor="middle">changed files</text>
<rect class="peach ink thin step" x="170" y="84" width="112" height="56" rx="12"/>
<text class="label" x="226" y="108" text-anchor="middle">Auto Link</text>
<text class="tiny" x="226" y="126" text-anchor="middle">dedupe + edges</text>
<rect class="pink ink thin step" x="38" y="168" width="112" height="56" rx="12"/>
<text class="label" x="94" y="192" text-anchor="middle">Integrate</text>
<text class="tiny" x="94" y="210" text-anchor="middle">write digest</text>
<rect class="mint ink thin step" x="170" y="168" width="112" height="56" rx="12"/>
<text class="label" x="226" y="192" text-anchor="middle">Proactive</text>
<text class="tiny" x="226" y="210" text-anchor="middle">interests.yaml</text>
<path class="arrow" d="M152 112 H168"/>
<path class="arrow" d="M226 142 V166"/>
<path class="arrow" d="M168 196 H152"/>
<path class="arrow" d="M94 166 V142"/>
</g>
<g transform="translate(730 120)">
<rect class="violet ink thin" x="0" y="0" width="430" height="260" rx="18"/>
<text class="head" x="215" y="31" text-anchor="middle">Auto Index + Memory Search</text>
<text class="text" x="215" y="56" text-anchor="middle">Keep indexes fresh, recall chunks, then follow links.</text>
<g transform="translate(24 86)">
<rect class="blue ink thin dash" x="0" y="0" width="178" height="136" rx="14"/>
<text class="label" x="89" y="24" text-anchor="middle">Auto Index</text>
<rect class="box ink thin step" x="18" y="46" width="64" height="58" rx="10"/>
<text class="label" x="50" y="70" text-anchor="middle">Watch</text>
<text class="tiny" x="50" y="88" text-anchor="middle">changes</text>
<rect class="yellow ink thin step" x="98" y="46" width="64" height="58" rx="10"/>
<text class="label" x="130" y="70" text-anchor="middle">Build</text>
<text class="tiny" x="130" y="88" text-anchor="middle">index</text>
<path class="arrow" d="M84 75 H96"/>
<path class="arrow" d="M152 112 H168"/>
<path class="arrow" d="M226 142 V166"/>
<path class="arrow" d="M168 196 H152"/>
<path class="arrow" d="M94 166 V142"/>
</g>
<g transform="translate(228 86)">
<rect class="green ink thin dash" x="0" y="0" width="178" height="136" rx="14"/>
<text class="label" x="89" y="24" text-anchor="middle">Memory Search</text>
<g transform="translate(730 120)">
<rect class="violet ink thin" x="0" y="0" width="430" height="260" rx="18"/>
<text class="head" x="215" y="31" text-anchor="middle">Auto Index + Memory Search</text>
<text class="text" x="215" y="56" text-anchor="middle" style="font-size:12px">Keep indexes fresh, recall chunks, then follow links.</text>
<rect class="box ink thin step" x="18" y="46" width="64" height="58" rx="10"/>
<text class="label" x="50" y="70" text-anchor="middle">Recall</text>
<text class="tiny" x="50" y="88" text-anchor="middle">BM25 + vec</text>
<g transform="translate(24 86)">
<rect class="blue ink thin dash" x="0" y="0" width="178" height="136" rx="14"/>
<text class="label" x="89" y="24" text-anchor="middle">Auto Index</text>
<rect class="mint ink thin step" x="98" y="46" width="64" height="58" rx="10"/>
<text class="label" x="130" y="70" text-anchor="middle">Expand</text>
<text class="tiny" x="130" y="88" text-anchor="middle">links</text>
<rect class="box ink thin step" x="18" y="46" width="64" height="58" rx="10"/>
<text class="label" x="50" y="70" text-anchor="middle">Watch</text>
<text class="tiny" x="50" y="88" text-anchor="middle">changes</text>
<path class="arrow" d="M84 75 H96"/>
<rect class="yellow ink thin step" x="98" y="46" width="64" height="58" rx="10"/>
<text class="label" x="130" y="70" text-anchor="middle">Build</text>
<text class="tiny" x="130" y="88" text-anchor="middle">index</text>
<path class="arrow" d="M84 75 H96"/>
</g>
<g transform="translate(228 86)">
<rect class="green ink thin dash" x="0" y="0" width="178" height="136" rx="14"/>
<text class="label" x="89" y="24" text-anchor="middle">Memory Search</text>
<rect class="box ink thin step" x="18" y="46" width="64" height="58" rx="10"/>
<text class="label" x="50" y="70" text-anchor="middle">Recall</text>
<text class="tiny" x="50" y="88" text-anchor="middle" style="font-size:10px">BM25 + vec</text>
<rect class="mint ink thin step" x="98" y="46" width="64" height="58" rx="10"/>
<text class="label" x="130" y="70" text-anchor="middle">Expand</text>
<text class="tiny" x="130" y="88" text-anchor="middle">links</text>
<path class="arrow" d="M84 75 H96"/>
</g>
<path class="arrow" d="M204 161 H226"/>
</g>
<path class="arrow" d="M204 161 H226"/>
</g>
<path class="arrow" d="M340 272 H380"/>
<path class="arrow" d="M340 272 H380"/>
<!-- Bottom foundation -->
<rect class="box ink" x="40" y="408" width="1120" height="202" rx="24"/>
<text class="head" x="600" y="442" text-anchor="middle">Memory as File</text>
<text class="text" x="600" y="466" text-anchor="middle">Every memory is readable, editable, indexable, linkable, and auditable as files.</text>
<!-- Bottom foundation -->
<rect class="box ink" x="40" y="408" width="1120" height="202" rx="24"/>
<text class="head" x="600" y="442" text-anchor="middle">Memory as File</text>
<text class="text" x="600" y="466" text-anchor="middle">Every memory is readable, editable, indexable, linkable, and auditable as files.</text>
<g transform="translate(94 500)">
<rect class="paper ink thin" x="10" y="6" width="62" height="52"/>
<rect class="paper ink thin" x="5" y="3" width="62" height="52"/>
<rect class="paper ink thin" x="0" y="0" width="62" height="52"/>
<rect class="tab ink thin" x="-12" y="14" width="44" height="22"/>
<text class="label" x="10" y="30" text-anchor="middle">.jsonl</text>
<line class="ink thin" x1="26" y1="28" x2="50" y2="28"/>
<line class="ink thin" x1="22" y1="42" x2="52" y2="42"/>
<text class="label" x="106" y="19">session/</text>
<text class="tiny" x="106" y="39">source conversations</text>
</g>
<g transform="translate(94 500)">
<rect class="paper ink thin" x="10" y="6" width="62" height="52"/>
<rect class="paper ink thin" x="5" y="3" width="62" height="52"/>
<rect class="paper ink thin" x="0" y="0" width="62" height="52"/>
<rect class="tab ink thin" x="-12" y="14" width="44" height="22"/>
<text class="label" x="10" y="30" text-anchor="middle">.json</text>
<line class="ink thin" x1="26" y1="28" x2="50" y2="28"/>
<line class="ink thin" x1="22" y1="42" x2="52" y2="42"/>
<text class="label" x="106" y="19">session/</text>
<text class="tiny" x="106" y="39">raw session logs</text>
</g>
<g transform="translate(344 500)">
<rect class="paper ink thin" x="10" y="6" width="62" height="52"/>
<rect class="paper ink thin" x="5" y="3" width="62" height="52"/>
<rect class="paper ink thin" x="0" y="0" width="62" height="52"/>
<rect class="tab ink thin" x="-8" y="14" width="34" height="22"/>
<text class="label" x="9" y="30" text-anchor="middle">.src</text>
<line class="ink thin" x1="26" y1="28" x2="50" y2="28"/>
<line class="ink thin" x1="22" y1="42" x2="52" y2="42"/>
<text class="label" x="106" y="19">resource/</text>
<text class="tiny" x="106" y="39">original source material</text>
</g>
<g transform="translate(344 500)">
<rect class="paper ink thin" x="10" y="6" width="62" height="52"/>
<rect class="paper ink thin" x="5" y="3" width="62" height="52"/>
<rect class="paper ink thin" x="0" y="0" width="62" height="52"/>
<rect class="tab ink thin" x="-8" y="14" width="34" height="22"/>
<text class="label" x="9" y="30" text-anchor="middle">.md</text>
<line class="ink thin" x1="26" y1="28" x2="50" y2="28"/>
<line class="ink thin" x1="22" y1="42" x2="52" y2="42"/>
<text class="label" x="106" y="19">resource/</text>
<text class="tiny" x="106" y="39">raw material with source</text>
</g>
<g transform="translate(604 500)">
<rect class="paper ink thin" x="10" y="6" width="62" height="52"/>
<rect class="paper ink thin" x="5" y="3" width="62" height="52"/>
<rect class="paper ink thin" x="0" y="0" width="62" height="52"/>
<rect class="tab ink thin" x="-8" y="14" width="34" height="22"/>
<text class="label" x="9" y="30" text-anchor="middle">.md</text>
<line class="ink thin" x1="26" y1="28" x2="50" y2="28"/>
<line class="ink thin" x1="22" y1="42" x2="52" y2="42"/>
<text class="label" x="106" y="19">daily/</text>
<text class="tiny" x="106" y="39">working memory cards</text>
</g>
<g transform="translate(604 500)">
<rect class="paper ink thin" x="10" y="6" width="62" height="52"/>
<rect class="paper ink thin" x="5" y="3" width="62" height="52"/>
<rect class="paper ink thin" x="0" y="0" width="62" height="52"/>
<rect class="tab ink thin" x="-8" y="14" width="34" height="22"/>
<text class="label" x="9" y="30" text-anchor="middle">.md</text>
<line class="ink thin" x1="26" y1="28" x2="50" y2="28"/>
<line class="ink thin" x1="22" y1="42" x2="52" y2="42"/>
<text class="label" x="106" y="19">daily/</text>
<text class="tiny" x="106" y="39">working memory cards</text>
</g>
<g transform="translate(850 500)">
<rect class="paper ink thin" x="10" y="6" width="62" height="52"/>
<rect class="paper ink thin" x="5" y="3" width="62" height="52"/>
<rect class="paper ink thin" x="0" y="0" width="62" height="52"/>
<rect class="tab ink thin" x="-8" y="14" width="34" height="22"/>
<text class="label" x="9" y="30" text-anchor="middle">.md</text>
<line class="ink thin" x1="26" y1="28" x2="50" y2="28"/>
<line class="ink thin" x1="22" y1="42" x2="52" y2="42"/>
<text class="label" x="106" y="19">digest/</text>
<text class="tiny" x="106" y="39">long-term knowledge nodes</text>
</g>
<g transform="translate(850 500)">
<rect class="paper ink thin" x="10" y="6" width="62" height="52"/>
<rect class="paper ink thin" x="5" y="3" width="62" height="52"/>
<rect class="paper ink thin" x="0" y="0" width="62" height="52"/>
<rect class="tab ink thin" x="-8" y="14" width="34" height="22"/>
<text class="label" x="9" y="30" text-anchor="middle">.md</text>
<line class="ink thin" x1="26" y1="28" x2="50" y2="28"/>
<line class="ink thin" x1="22" y1="42" x2="52" y2="42"/>
<text class="label" x="106" y="19">digest/</text>
<text class="tiny" x="106" y="39">long-term knowledge nodes</text>
</g>
<path class="soft-arrow" d="M190 380 V408"/>
<path class="soft-arrow" d="M540 380 V408"/>
<path class="soft-arrow" d="M945 380 V408"/>
<path class="soft-arrow" d="M190 380 V408"/>
<path class="soft-arrow" d="M540 380 V408"/>
<path class="soft-arrow" d="M945 380 V408"/>
</svg>

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 11 KiB

After

Width:  |  Height:  |  Size: 11 KiB

87
docs/zh/auto_dream.md
View file

@ -1,7 +1,8 @@
# Auto Dream
`auto_dream` 是 ReMe 的 daily 到 digest 的长期记忆沉淀流程。它扫描指定日期的 daily 输入，只处理相对上次 dream
发生变化的文件，把值得长期保留的内容抽取成 memory units，整合进 `digest/`，再生成当天可供主动提醒使用的 `interests.yaml`。
`auto_dream` 是 ReMe 的 daily 到 digest 的长期记忆沉淀流程。它默认扫描目标日期及前一天的 daily 输入，只处理相对上次 dream
发生变化的文件，从整个扫描窗口中抽取少量高价值 memory units，整合进 `digest/`，再生成目标日期可供主动提醒使用的
`interests.yaml`。
<p align="center">
<img src="../figure/auto-dream-and-proactive.svg" alt="ReMe Auto Dream and Proactive 从 daily 到 digest 再到 proactive 的流程" width="92%">
@ -25,6 +26,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
@ -35,6 +42,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
@ -45,32 +54,36 @@ auto_dream:
参数含义：
| 参数 | 作用 |
|------------------------|------------------------------------------------|
| `date` | 要处理的日期，格式为 `YYYY-MM-DD`。为空时使用应用时区中的今天。 |
| `hint` | 调用方给抽取和整合阶段的额外指导。 |
| `topic_count` | 最终写入 `interests.yaml` 的 topic 上限，默认 3。 |
| 参数 | 作用 |
|------------------------|-------------------------------------------------------------------|
| `date` | 要处理的日期，格式为 `YYYY-MM-DD`。为空时使用应用时区中的今天。 |
| `hint` | 调用方给抽取和整合阶段的额外指导。 |
| `scan_days` | 以 `date` 结尾的最近日期窗口；默认扫描 2 天，最小为 1。 |
| `max_units` | 一次最多抽取多少个可复用 unit；默认 5。 |
| `topic_count` | 最终写入 `interests.yaml` 的 topic 上限，默认 3。 |
| `topic_diversity_days` | 选择 topic 时参考过去多少天的 `interests.yaml` 避免重复，默认 7。 |
## 输入和输出
输入来自指定日期的 daily markdown：
输入来自以指定日期结尾的最近 `scan_days` 天 daily markdown。例如 `date=2026-06-20`、`scan_days=2` 时会扫描：
```text
daily/<date>.md
daily/<date>/**/*.md
daily/2026-06-19.md
daily/2026-06-19/**/*.md
daily/2026-06-20.md
daily/2026-06-20/**/*.md
```
`daily/<date>/interests.yaml` 不作为抽取输入，避免上一轮主动主题反过来污染下一轮抽取。
扫描窗口内的 `daily/<date>/interests.yaml` 都不作为抽取输入，避免上一轮主动主题反过来污染下一轮抽取。最终 topic 只写入目标日期。
主要输出有三类：
| 输出 | 说明 |
|-------------------------------------|-------------------------------------|
| `digest/procedure/*.md` | 方法、流程、runbook、可执行经验。 |
| `digest/personal/*.md` | 用户、团队、项目相关的偏好、事实、长期上下文。 |
| `digest/wiki/*.md` | 通用知识、概念、观察、决策先例。 |
| `daily/<date>/interests.yaml` | 当天值得上层 Agent 主动关注的兴趣主题。 |
| 输出 | 说明 |
|--------------------------------|---------------------------------------------------|
| `digest/procedure/*.md` | 方法、流程、runbook、可执行经验。 |
| `digest/personal/*.md` | 用户、团队、项目相关的偏好、事实、长期上下文。 |
| `digest/wiki/*.md` | 通用知识、概念、观察、决策先例。 |
| `daily/<date>/interests.yaml` | 当天值得上层 Agent 主动关注的兴趣主题。 |
| `metadata/file_catalog/dream*` | dream 专用 catalog，用于判断 daily 输入是否变化。 |
## 四个阶段
@ -79,16 +92,18 @@ daily/<date>/**/*.md
`dream_extract_step` 做三件事：
1. 刷新当天索引页 `daily/<date>.md`。
2. 扫描 `daily/<date>.md` 和 `daily/<date>/**/*.md`，与 `file_catalog: dream` 中记录的 mtime 对比。
3. 只把 changed files 交给 LLM，全局抽取两类结构化结果：`units` 和 `topics`。
1. 刷新扫描窗口内每天的索引页 `daily/<date>.md`。
2. 扫描这些日期的索引页和 `daily/<date>/**/*.md`，与 `file_catalog: dream` 中记录的 mtime 对比。
3. 只把 changed files 一起交给 LLM，全局抽取两类结构化结果：`units` 和 `topics`。
`units` 是准备沉淀进 digest 的长期记忆单元，包含 `name`、`bucket`、`summary`、`paths`。`bucket` 只允许 `procedure`、
`personal`、`wiki`；未知值会路由到 `wiki`。
`units` 是准备沉淀进 digest 的长期记忆单元，包含 `name`、`bucket`、`summary`、`paths`。一次最多返回 `max_units`
个，抽取器会优先合并指向同一抽象的跨文件证据，并丢弃短暂提及、逐文件摘要和缺少复用价值的弱候选。`bucket` 只允许
`procedure`、`personal`、`wiki`；未知值会路由到 `wiki`。
`topics` 是当天主动兴趣候选，包含 `title`、`reason`、`evidence`、`keywords`、`paths`，后续由 Topics 阶段再筛选。
如果没有 changed files，流程会提前成功结束后续抽取工作；如果有变化但没有配置 LLM，Extract 会失败，因为抽取依赖 LLM。
如果没有 changed files，Extract 会成功返回空 units；Integrate 随后没有 unit 可处理，Topics 保留目标日期已有的 topics，Finish
仍会正常汇总 catalog。如果有变化但没有配置 LLM，Extract 会失败，因为抽取依赖 LLM。
### 2. Integrate
@ -101,14 +116,17 @@ node_search, read, frontmatter_read, write, edit, frontmatter_update
这一阶段承担 `auto_link` 的核心职责：先用 `node_search` 在 digest 节点级召回相似或相关节点，再判断是新建还是更新，最后把来源和相关
digest 节点写成 wikilink。具体召回、去重和写边规则见 [Auto Link](./auto_link.md)。
Extract 已经承担“是否值得长期记住”的过滤，因此 Integrate 不提供 `SKIP` 动作：每个进入本阶段的 unit 都应落到且只落到一个
digest 节点。新增与更新都必须保留来源，并把相关 digest 链接写进有上下文的句子；不能只写裸 Wikilink 或独立的关系字段。
整合动作只有四种：
| 动作 | 含义 |
|---------------|-------------------------|
| `CREATE` | 没有相同抽象，创建新的 digest 节点。 |
| `CORROBORATE` | 同一记忆再次出现，追加来源或强化表述。 |
| 动作 | 含义 |
|---------------|------------------------------------------------|
| `CREATE` | 没有相同抽象，创建新的 digest 节点。 |
| `CORROBORATE` | 同一记忆再次出现，追加来源或强化表述。 |
| `REFINE` | 新材料补充了边界、步骤、前提、适用范围或细节。 |
| `CORRECT` | 新材料修正了旧节点的错误、遗漏或冲突。 |
| `CORRECT` | 新材料修正了旧节点的错误、遗漏或冲突。 |
Integrate 成功的 unit 会记录到 `integrate_results`；失败的 unit 会进入 `failed_units`，其来源路径会进入 `failed_paths`。
Finish 阶段不会 checkpoint 失败路径，保证下次还能重试。
@ -121,7 +139,7 @@ Finish 阶段不会 checkpoint 失败路径，保证下次还能重试。
```text
daily/<date>/interests.yaml
daily/<previous-date>/interests.yaml
daily/<过去 topic_diversity_days 天中的每一天>/interests.yaml
```
同一天已有 topics 会被保留，最近 `topic_diversity_days` 天出现过的相似主题会被去重。默认最多写 3 个 topic。配置了 LLM 时会让
@ -149,7 +167,7 @@ topics:
`dream_finish_step` 负责收尾：
1. 将成功处理的 changed paths 写入 `file_catalog: dream`。
2. 将 `daily/<date>/interests.yaml` 和 `daily/<date>.md` 也写入 catalog。
2. 将目标日期的 `daily/<date>/interests.yaml` 和扫描窗口内每个已刷新的 day-index 页也写入 catalog。
3. 如果有 upsert 或 delete，持久化 dream catalog。
4. 返回包含 scanned、changed、integrated、topics、checkpoint 等计数的摘要。
@ -169,6 +187,12 @@ reme auto_dream date=2026-06-20
reme auto_dream date=2026-06-20 hint="优先沉淀工程决策和长期偏好"
```
覆盖默认扫描窗口和 unit 上限：
```bash
reme auto_dream date=2026-06-20 scan_days=3 max_units=8
```
也可以在配置中把同一组 step 放进 `cron` job，例如每天凌晨运行：
```yaml
@ -189,7 +213,8 @@ jobs:
`auto_dream` 只消费 daily 输入，不改写 daily 正文。daily 是事实和现场记录，digest 才是抽象后的长期记忆层。
`digest` 不是原文复制。正文应保留可复用抽象，细节通过 Sources 章节中的 `- [[daily/<date>/...]]` 指回来源。链接写法遵循
`digest` 不是原文复制。正文应保留可复用抽象，Sources 章节用带上下文的完整句子指回来源，例如
`该决策记录在 [[daily/<date>/decision.md]] 中。`链接写法遵循
[Memory as File](./memory_as_file.md) 中的 workspace-relative wikilink 语义。
`auto_dream` 不凭空生成总览。只有 daily 输入中确实出现、并被抽取为 unit 或 topic 的内容，才会进入 digest 或

49
docs/zh/auto_link.md
View file

@ -26,12 +26,12 @@ Integrate 阶段对每个 unit 独立运行。一个 unit 只落到一个目标
`auto_link` 解决的是写入时的图谱质量问题：
| 问题 | 处理方式 |
|--------------|----------------------------------------------------|
| 已有相同记忆 | 召回后更新旧节点，而不是重复创建。 |
| 新旧材料有关联 | 在正文中写入 workspace-relative wikilink。 |
| 问题 | 处理方式 |
|-------------------|------------------------------------------------------|
| 已有相同记忆 | 召回后更新旧节点，而不是重复创建。 |
| 新旧材料有关联 | 在正文中写入 workspace-relative wikilink。 |
| digest 与来源断开 | 在 `## Sources` 章节加入指向 daily/resource 的链接。 |
| 节点只有孤立正文 | 在 CREATE 和 UPDATE 时都补充相关 digest 节点链接。 |
| 节点只有孤立正文 | 在 CREATE 和 UPDATE 时都补充相关 digest 节点链接。 |
## 工具链
@ -60,22 +60,22 @@ Agent 先用 unit 的触发条件、动词、名词、同义词和可能的 fail
召回结果会被内部分成三类：
| 分类 | 含义 | 后续动作 |
|--------------------|-----------------------------|----------------|
| `same_abstraction` | 触发条件或抽象本质相同，内容实质重叠。 | 作为 UPDATE 目标。 |
| 分类 | 含义 | 后续动作 |
|--------------------|--------------------------------------------------------|---------------------|
| `same_abstraction` | 触发条件或抽象本质相同，内容实质重叠。 | 作为 UPDATE 目标。 |
| `related` | 相邻流程、前置条件、失败模式、概念、偏好或上下游知识。 | 写入正文 wikilink。 |
| `unrelated` | 只是表面相似或无关。 | 忽略。 |
| `unrelated` | 只是表面相似或无关。 | 忽略。 |
### 2. 选择写入动作
每个 unit 必须选择一个动作：
| 动作 | 链接含义 |
|---------------|-----------------------------------------------------|
| 动作 | 链接含义 |
|---------------|----------------------------------------------------------------------------|
| `CREATE` | 写入新的 `digest/<bucket>/<slug>.md`，并在新正文里加入来源和相关节点链接。 |
| `CORROBORATE` | 同一抽象再次出现，追加来源链接，必要时强化描述。 |
| `REFINE` | 新材料扩展了旧节点，把补充内容插入合适段落，并保留旧链接。 |
| `CORRECT` | 新材料修正旧节点，用来源链接标出修正依据。 |
| `CORROBORATE` | 同一抽象再次出现，追加来源链接，必要时强化描述。 |
| `REFINE` | 新材料扩展了旧节点，把补充内容插入合适段落，并保留旧链接。 |
| `CORRECT` | 新材料修正旧节点，用来源链接标出修正依据。 |
UPDATE 必须尽量只增不删：不要删除已有 wikilink 或来源条目。这是为了让后续图谱索引和检索不会丢边。
@ -86,11 +86,12 @@ UPDATE 必须尽量只增不删：不要删除已有 wikilink 或来源条目。
```markdown
## Sources
- [[daily/2026-06-20/session.md]]
- [[resource/2026-06-20/paper.md]]
该决策记录在 [[daily/2026-06-20/session.md]] 中，支撑它的技术证据来自
[[resource/2026-06-20/paper.md]]。
```
这些边表示 digest 节点的证据来源。纯文本描述不算来源边，因为只有 wikilink 能被 file graph 稳定解析。更完整的 wikilink
这些边表示 digest 节点的证据来源。纯文本描述不算来源边，因为只有 wikilink 能被 file graph 稳定解析；外层完整句子还必须说明每个来源支持什么，
裸 Wikilink 单独成行不是合法的 Integrate 输出。更完整的 wikilink
解析规则见 [Memory as File](./memory_as_file.md#wikilink)。
### 4. 写 digest 关联边
@ -107,11 +108,11 @@ digest 之间的关联使用完整 workspace-relative 路径，并自然织入
`auto_link` 的规则会随 unit bucket 调整写入形态：
| Bucket | 写入重点 |
|-------------|---------------------------------------------|
| Bucket | 写入重点 |
|-------------|--------------------------------------------------------------------------------|
| `procedure` | 写成 runbook：触发条件、步骤、输入、失败模式。链接前置流程、子步骤、相关偏好。 |
| `personal` | 写用户、团队、项目特定事实或偏好。链接相关项目、习惯、决策背景。 |
| `wiki` | 写通用知识、原则、观察、决策先例。链接概念、方法、相邻知识。 |
| `personal` | 写用户、团队、项目特定事实或偏好。链接相关项目、习惯、决策背景。 |
| `wiki` | 写通用知识、原则、观察、决策先例。链接概念、方法、相邻知识。 |
无论 bucket 是什么，都要保留来源边，并尽量把召回到的相关 digest 节点织入正文。
@ -119,9 +120,9 @@ digest 之间的关联使用完整 workspace-relative 路径，并自然织入
`auto_link` 使用的是 `node_search`，不是面向问答的 `search`。
| 能力 | 用途 |
|---------------|-------------------------------------------|
| `search` | 面向外部问答，返回 chunk，并可展开上下游 link context。 |
| 能力 | 用途 |
|---------------|---------------------------------------------------------------------|
| `search` | 面向外部问答，返回 chunk，并可展开上下游 link context。 |
| `node_search` | 面向 dream 集成，只召回 digest 节点级摘要，用来判断去重和相关链接。 |
这个边界很重要：Integrate 阶段需要的是“是否已有相同抽象，以及应该链接哪些节点”，而不是直接把大量正文片段塞进上下文。

41
docs/zh/auto_memory.md
View file

@ -1,7 +1,7 @@
# Auto Memory
Auto Memory 是 ReMe 的对话记忆入口：每段对话先按 `session_id` 沉淀成一张 daily 记忆卡片，再由当天的 `YYYY-MM-DD.md`
统一索引。它负责把“聊过”变成“记住”，并把原始对话留好出处。
Auto Memory 是 ReMe 的对话记忆入口：在目标日期内，它用 `session_id` 定位或更新最多一张 daily 记忆卡片，文件名由 Agent
根据内容生成简洁的主题或事件名，再由当天的 `YYYY-MM-DD.md` 统一索引。它负责把“聊过”变成“记住”，并保留可追溯的对话记录。
<p align="center">
<img src="../figure/auto-memory-resource.svg" alt="ReMe Auto Memory 与 Auto Resource 写入 daily 记忆卡片的流程" width="92%">
@ -11,9 +11,9 @@ Auto Memory 是 ReMe 的对话记忆入口：每段对话先按 `session_id` 沉
```text
Conversation
├─ step 1: daily/YYYY-MM-DD/<session_id>.md # 每段对话先成卡片
├─ step 2: daily/YYYY-MM-DD.md # 当天索引再串起来
└─ source: session/dialog/<session_id>.jsonl # 原始对话
├─ step 1: daily/YYYY-MM-DD/<generated_name>.md # 每个 session 一张主题卡片
├─ step 2: daily/YYYY-MM-DD.md # 当天索引再串起来
└─ source: session/dialog/<session_id>.jsonl # 对话来源记录
```
## 它记录什么
@ -37,27 +37,29 @@ 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`、`daily/2026-06-20/session-b.md` 是不同对话整理出的记忆卡片，
`daily/2026-06-20.md` 是当天索引页。资源文件也会进入同一个 daily 记忆层，见 [Auto Resource](./auto_resource.md)。
日期目录下的两个文件是不同对话整理出的主题卡片，`daily/2026-06-20.md` 是当天索引页。资源文件也会进入
同一个 daily 记忆层，见 [Auto Resource](./auto_resource.md)。
当调用时带上 `session_id`，Auto Memory 会按这个 id 单独记录这段对话：
当调用时带上 `session_id`，Auto Memory 会通过 frontmatter 用它定位卡片，Agent 则通过 `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]]"
```
这样不同对话不会混在一起。一次需求讨论、一次问题排查、一次文档修改，都可以拥有自己的记忆卡片。以后想知道这一天发生了什么，先看
`YYYY-MM-DD.md`；想看某段对话沉淀了什么，再进入对应的 `<session_id>.md`。
这样既能分开不同对话，又不必把不透明的 ID 当文件名。更新时会按 `session_id` 或 `source_conversation` 找到旧卡片；如果 Agent
提供了更好的 frontmatter `name`，系统可重命名并重定向入链。查看某天内容时从 `YYYY-MM-DD.md` 开始。
## 同时保存原始信息
整理后的 daily note 负责“好读”，原始对话负责“可信”。
整理后的 daily note 负责“好读”，过滤后的对话来源记录负责“可信”。
Auto Memory 在生成记忆卡片的同时，也会保存原始会话：
Auto Memory 在生成记忆卡片的同时，也会保存对话来源消息：
```text
session/
@ -66,11 +68,12 @@ session/
session-b.jsonl
```
daily note 会指向对应的原始对话。需要核对某条记忆时，可以顺着链接回到当时的完整上下文。
daily note 会指向对应的对话记录。持久化时会排除 tool-result block 和 base64 data block，避免召回记忆或二进制负载在后续流程中被误当成
用户提供的证据。
## 消息时间
Auto Memory 会在 prompt 和原始会话 JSONL 中保留每条消息的 `created_at`。导入历史对话或 benchmark 数据时，建议为每条
Auto Memory 会在 prompt 和对话来源 JSONL 中保留每条已保留消息的 `created_at`。导入历史对话或 benchmark 数据时，建议为每条
message 提供真实发生时间，避免模型把事件时间误解为运行时间：
```bash
@ -85,7 +88,7 @@ reme auto_memory \
为了兼容常见数据集字段，`auto_memory` 也会在缺少 `created_at` 时读取 `time_created`、`timestamp`、`createdAt`、
`timeCreated` 或 `created_time`。这些字段可以放在 message 顶层，也可以放在 `metadata` 中。
当调用没有显式传入 `date` 时，Auto Memory 会使用消息中最早的有效 `created_at` 日期作为 daily note 日期；如果消息没有有效时间，
当调用没有显式传入 `date` 时，Auto Memory 会使用消息中最晚的有效 `created_at` 日期作为 daily note 日期；如果消息没有有效时间，
则回退到当前日期。历史导入也可以显式指定目标日期：
```bash

25
docs/zh/auto_resource.md
View file

@ -1,7 +1,8 @@
# Auto Resource `Beta`
Auto Resource 是 ReMe 的资源解读入口，目前处于 **Beta**。资源文件先按日期进入 `resource/`，再被解读成 daily
资源卡片；卡片文件名由 LLM 生成的 frontmatter `name` 决定，并通过 `source_resource` 追溯原始文件。
Auto Resource 是 ReMe 的资源解读入口，目前处于 **Beta**。资源文件先进入 `resource/`（推荐按日期放置），再被解读成 daily
资源卡片；卡片文件名由 LLM 生成的 frontmatter `name` 决定，并通过 `source_resource`
追溯原始文件。
<p align="center">
<img src="../figure/auto-memory-resource.svg" alt="ReMe Auto Memory 与 Auto Resource 写入 daily 记忆卡片的流程" width="92%">
@ -11,7 +12,7 @@ Auto Resource 是 ReMe 的资源解读入口，目前处于 **Beta**。资源文
[Auto Memory](./auto_memory.md)。
```text
resource/YYYY-MM-DD/<resource_file>
resource/[YYYY-MM-DD/]<resource_file>
├─ step 1: daily/YYYY-MM-DD/<generated_name>.md # 资源解读卡片
├─ step 2: source_resource 指回原始资源
└─ step 3: daily/YYYY-MM-DD.md # 当天索引再串起来
@ -31,13 +32,15 @@ resource/YYYY-MM-DD/<resource_file>
## 原始资料入口
Auto Resource 以 `resource/` 作为原始资料入口。资源需要按日期放置，这个日期会决定它进入哪一天的 daily 记忆层。
Auto Resource 以 `resource/` 作为原始资料入口。推荐按日期放置，目录日期会决定它进入哪一天的 daily 记忆层；也支持直接放在
`resource/` 根目录，此时使用应用时区中的今天。
示例目录：
```text
workspace/
resource/
quick-note.txt # 进入今天的 daily
2026-06-20/
market-report.md
meeting-notes.csv
@ -47,8 +50,8 @@ workspace/
## 资源卡片
每个资源文件会生成一张 daily 资源卡片。创建时先使用资源文件 stem 作为临时路径，Agent 写入后，系统会根据
frontmatter `name` 重命名文件：
每个资源文件会生成一张 daily 资源卡片。创建时先使用资源文件 stem 作为临时路径，Agent 写入后，系统会根据 frontmatter `name`
重命名文件：
```text
resource/2026-06-20/market-report.md
@ -62,8 +65,8 @@ daily/2026-06-20/市场报告要点.md
source_resource: "[[resource/2026-06-20/market-report.md]]"
```
如果资源文件更新，Auto Resource 会通过 `source_resource` 找到对应卡片并更新；如果资源文件删除，对应的 daily note
也会被清理。旧版本按 stem 生成的 `daily/YYYY-MM-DD/<resource_stem>.md` 仍作为 fallback 兼容。
如果资源文件更新，Auto Resource 会通过 `source_resource` 找到对应卡片并更新；如果资源文件删除，对应的 daily note 也会被清理。旧版本按
stem 生成的 `daily/YYYY-MM-DD/<resource_stem>.md` 仍作为 fallback 兼容。
## 当天索引
@ -83,9 +86,9 @@ daily/
解读后的 daily note 负责“好读”，原始资源负责“可信”。
Auto Resource 不会把原始文件挪走：它仍然留在 `resource/YYYY-MM-DD/`。这样，文本资料会进入 daily 记忆流，原始文件也始终保留在它来时的位置。
Auto Resource 不会把原始文件挪走：它仍然留在 `resource/` 下的原路径。这样，文本资料会进入 daily 记忆流，原始文件也始终保留在它来时的位置。
## 后续流向
Auto Resource 只生成 daily 层的资源解读。要把资源中的长期知识沉淀进 `digest/`，使用 [Auto Dream](./auto_dream.md)；要检索原始资源、
daily 卡片和 digest 节点，使用 [Memory Search](./memory_search.md)。
Auto Resource 只生成 daily 层的资源解读。要把资源中的长期知识沉淀进 `digest/`，使用 [Auto Dream](./auto_dream.md)；默认实时检索会
索引 daily 卡片和 digest 节点。若还要直接检索原始资源文件，可运行 `reme reindex`，详见 [Memory Search](./memory_search.md)。

18
docs/zh/contributing.md
View file

@ -71,14 +71,14 @@ CLI / Client -> Service -> Application -> Job -> Step -> Component / Workspace
根据改动类型选择合适的入口：
| 改动类型 | 主要位置 | 建议 |
|------------|-----------------------------------------------------|---------------------------------------------------------------------------|
| 配置或启动行为 | `reme/config/`、`reme/application.py`、`reme/reme.py` | 保持默认配置可运行，避免破坏现有 CLI、HTTP 和 MCP 入口 |
| 组件能力 | `reme/components/` | 优先复用 `BaseComponent`、registry 和上下文对象 |
| Job 或 Step | `reme/components/job/`、`reme/steps/` | 遵照 [ReMe 代码框架](./framework.md) 的 Job -> Step 范式，保持请求、响应 schema 清晰，并补充对应测试 |
| 数据结构 | `reme/schema/`、`reme/enumeration/` | 注意序列化兼容性和已有 front matter、wikilink 语义 |
| 工具函数 | `reme/utils/` | 保持函数边界小，并用单元测试覆盖边界情况 |
| 用户文档 | `docs/zh/`、`README.md` | 当用户可见行为变化时同步更新文档 |
| 改动类型 | 主要位置 | 建议 |
|----------------|-------------------------------------------------------|------------------------------------------------------------------------------------------------------|
| 配置或启动行为 | `reme/config/`、`reme/application.py`、`reme/reme.py` | 保持默认配置可运行，避免破坏现有 CLI、HTTP 和 MCP 入口 |
| 组件能力 | `reme/components/` | 优先复用 `BaseComponent`、registry 和上下文对象 |
| Job 或 Step | `reme/components/job/`、`reme/steps/` | 遵照 [ReMe 代码框架](./framework.md) 的 Job -> Step 范式，保持请求、响应 schema 清晰，并补充对应测试 |
| 数据结构 | `reme/schema/`、`reme/enumeration/` | 注意序列化兼容性和已有 front matter、wikilink 语义 |
| 工具函数 | `reme/utils/` | 保持函数边界小，并用单元测试覆盖边界情况 |
| 用户文档 | `docs/zh/`、`README.md` | 当用户可见行为变化时同步更新文档 |
如果改动涉及 LLM、embedding、外部服务、文件监听或后台任务，请同时说明依赖条件、失败行为和本地验证方式。
@ -199,7 +199,7 @@ docs/
- Bugs 和功能请求：[GitHub Issues](https://github.com/agentscope-ai/ReMe/issues)
- 项目主页：[GitHub Repository](https://github.com/agentscope-ai/ReMe)
- 文档站点：[https://reme.agentscope.io/](https://reme.agentscope.io/)
- 文档站点：[https://docs.agentscope.io/reme](https://docs.agentscope.io/reme)
---

206
docs/zh/framework.md
View file

@ -2,8 +2,8 @@
## 1. 总览
ReMe 的运行时可以理解为：**配置驱动的 Application 把组件和 Job 装配起来，Service 把可服务的 Job 暴露给 CLI、HTTP 或 MCP，Job
再按顺序执行 Step**。
ReMe 的运行时可以理解为：**配置驱动的 Application 把组件和 Job 装配起来，Service 把可服务的 Job 暴露给 CLI、HTTP 或
MCP，Job 再按顺序执行 Step**。
<p align="center">
<img src="../figure/framework-structure.svg" alt="ReMe 代码框架结构：CLI、Service、Application、Job、Step 与 Component" width="92%">
@ -33,16 +33,16 @@ flowchart LR
核心分层：
| 层 | 主要目录 | 职责 |
|-------------|----------------------------|--------------------------------------------------------------|
| CLI | `reme/reme.py` | 解析命令；`start` 启动服务；其他 action 通过 client 调用服务 |
| Service | `reme/components/service/` | 把 Job 注册成 HTTP endpoint 或 MCP tool |
| Application | `reme/application.py` | 读取配置后的对象装配、依赖拓扑启动、关闭、Job 调用 |
| Job | `reme/components/job/` | 编排一组 Step；决定同步、流式、后台、定时运行方式 |
| Step | `reme/steps/` | 业务原子操作，例如读写文件、检索、索引、自进化 |
| 层 | 主要目录 | 职责 |
|-------------|----------------------------|---------------------------------------------------------------------------|
| CLI | `reme/reme.py` | 解析命令；`start` 启动服务；其他 action 通过 client 调用服务 |
| Service | `reme/components/service/` | 把 Job 注册成 HTTP endpoint 或 MCP tool |
| Application | `reme/application.py` | 读取配置后的对象装配、依赖拓扑启动、关闭、Job 调用 |
| Job | `reme/components/job/` | 编排一组 Step；决定同步、流式、后台、定时运行方式 |
| Step | `reme/steps/` | 业务原子操作，例如读写文件、检索、索引、自进化 |
| Component | `reme/components/` | 可复用基础设施，例如 file_store、file_graph、keyword_index、agent_wrapper |
| Schema | `reme/schema/` | `Request`、`Response`、`FileChunk`、`FileNode`、配置模型等数据结构 |
| Config | `reme/config/` | 默认 YAML 配置和命令行覆盖解析 |
| Config | `reme/config/` | 默认 YAML 配置和命令行覆盖解析 |
## 2. 目录结构
@ -63,18 +63,19 @@ reme/
file_store/ # 文件索引协调层
file_graph/ # wikilink 图谱
keyword_index/ # BM25 等关键词索引
file_chunker/ # Markdown / 默认文本分块
file_chunker/ # Markdown / JSON / JSONL / 通用文本分块
file_catalog/ # 变更 checkpoint
as_llm/, as_embedding/ # 模型封装
agent_wrapper/ # AgentScope / Claude Code wrapper
agent_wrapper/ # AgentScope / Claude Code / Codex wrapper
steps/
base_step.py # BaseStep、Ref、dispatch_steps
common/ # version、help、health_check、demo
common/ # version、help、health_check、status、chat
benchmark/ # LongMemEval / BEAM 评测步骤
cookbook/ # 可选研究工作流步骤
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 工具
transfer/ # upload/download
```
默认 workspace 目录由 `ApplicationConfig` 定义：
@ -82,7 +83,8 @@ reme/
```text
<workspace_dir>/
metadata/ # file_store、file_graph、keyword_index、file_catalog 等持久状态
session/ # Agent session 与原始对话
session/ # 记忆工作流使用的对话来源记录
mem_session/ # Agent wrapper 生成的 session 和配置
resource/ # 外部资源
daily/ # 浅加工记忆
digest/ # 长期 digest 记忆
@ -122,21 +124,21 @@ reme search query="memory" backend=mcp
配置解析支持：
| 能力 | 源码 | 说明 |
|--------------|-------------------------|---------------------------------------------|
| 默认配置 | `resolve_app_config()` | 未指定 `config` 时加载 `reme/config/default.yaml` |
| 指定配置 | `config=<name-or-path>` | 可传内置配置名或 YAML/JSON 文件路径 |
| dot notation | `parse_dot_notation()` | 例如 `service.port=8181` |
| 环境变量 | `_expand_env_vars()` | 支持 `${VAR}` 和 `${VAR:-default}` |
| 值转换 | `_convert_value()` | bool、int、float、JSON list/dict/null 会自动转换 |
| 能力 | 源码 | 说明 |
|--------------|-------------------------|---------------------------------------------------|
| 默认配置 | `resolve_app_config()` | 未指定 `config` 时加载 `reme/config/default.yaml` |
| 指定配置 | `config=<name-or-path>` | 可传内置配置名或 YAML/JSON 文件路径 |
| dot notation | `parse_dot_notation()` | 例如 `service.port=8181` |
| 环境变量 | `_expand_env_vars()` | 支持 `${VAR}` 和 `${VAR:-default}` |
| 值转换 | `_convert_value()` | bool、int、float、JSON list/dict/null 会自动转换 |
### 3.2 Service
`BaseService.run_app()` 的顺序：
可通过可选的 `service.jobs` 列表将 HTTP 或 MCP 仅暴露给指定 Job。未配置时，所有 `enable_serve: true` 的 Job
仍可被暴露；配置为空列表时不暴露任何 Job。该白名单不会覆盖 `enable_serve: false`。
配置该列表后，缺失、禁用、不受支持或无效的已选 Job 会导致服务启动失败。
仍可被暴露；配置为空列表时不暴露任何 Job。该白名单不会覆盖 `enable_serve: false`。配置该列表后，缺失、禁用、不受支持或无效的已选
Job 会导致服务启动失败。
```mermaid
flowchart LR
@ -152,19 +154,23 @@ flowchart LR
HTTP service 行为：
| Job 类型 | HTTP 暴露方式 |
|--------------------------------------|-------------------------------------------|
| Job 类型 | HTTP 暴露方式 |
|----------------------------------------|----------------------------------------------|
| 非 `StreamJob` 且 `enable_serve: true` | `POST /<job.name>`，返回 `Response` JSON |
| `StreamJob` | `POST /<job.name>`，返回 `text/event-stream` |
| `enable_serve: false` | 不注册 endpoint |
| `StreamJob` | `POST /<job.name>`，返回 `text/event-stream` |
| `enable_serve: false` | 不注册 endpoint |
HTTP service 还可以在所有 Job endpoint 注册完成后挂载 ReMe Studio 单页应用。默认 `service.web_enabled=true`；构建产物按
`service.web_static_dir`、`REME_WEB_STATIC_DIR`、包内 `reme/web` 和源码树 `website/dist-static` 等候选位置解析。找不到
`index.html` 时只跳过前端，Job API 仍然可用。Studio 的 `GET` fallback 不会覆盖已有的 `POST /<job.name>`。
MCP service 行为：
| Job 类型 | MCP 暴露方式 |
|--------------------------------------|---------------------------------|
| 非 `StreamJob` 且 `enable_serve: true` | 注册为 MCP tool |
| `StreamJob` | 当前跳过，不注册 |
| `BackgroundJob` | 构造时强制 `enable_serve=False`，不会暴露 |
| Job 类型 | MCP 暴露方式 |
|----------------------------------------|-------------------------------------------|
| 非 `StreamJob` 且 `enable_serve: true` | 注册为 MCP tool |
| `StreamJob` | 当前跳过，不注册 |
| `BackgroundJob` | 构造时强制 `enable_serve=False`，不会暴露 |
MCP 服务可通过 `injected_job_kwargs` 注入由服务端管理的参数，调用方不能覆盖这些参数。设置
`tool_error_on_failure: true` 后，不成功的 ReMe `Response` 会作为 MCP tool error 返回。
@ -192,7 +198,7 @@ class VersionStep(BaseStep):
其中 `component_type` 来自类属性，例如：
| 类型 | 类属性 |
| 类型 | 类属性 |
|-----------|-----------------------------------------------------------|
| Step | `BaseStep.component_type = ComponentEnum.STEP` |
| Job | `BaseJob.component_type = ComponentEnum.JOB` |
@ -204,7 +210,8 @@ class VersionStep(BaseStep):
### 4.2 模块导入触发注册
注册发生在模块 import 时。`reme/components/__init__.py` 会 import 各组件包，`reme/steps/__init__.py` 会 import
`channel/common/evolve/file_io/index/transfer`。这些包的 `__init__.py` 再 import 具体模块，从而执行 `@R.register(...)`。
`benchmark/common/cookbook/evolve/file_io/index/transfer`。这些包的 `__init__.py` 再 import 具体模块，从而执行
`@R.register(...)`。
新增 Step 文件后，必须保证它所在包的 `__init__.py` 会 import 该模块，否则注册表里找不到这个 backend。
@ -225,13 +232,13 @@ flowchart LR
`BaseComponent.bind(name, BaseClass, optional=True)` 的规则：
| 场景 | 行为 |
|------------------------|--------------------------------------------|
| `name` 为空 | 返回 `None`，跳过依赖 |
| `app_context` 存在 | 从 `app_context.components[ctype][name]` 查找 |
| 场景 | 行为 |
|-----------------------------|-----------------------------------------------|
| `name` 为空 | 返回 `None`，跳过依赖 |
| `app_context` 存在 | 从 `app_context.components[ctype][name]` 查找 |
| 依赖缺失且 `optional=True` | 解析为 `None` |
| 依赖缺失且 `optional=False` | 启动时报错 |
| standalone 模式 | 可用 `default_factory` 创建自有组件 |
| 依赖缺失且 `optional=False` | 启动时报错 |
| standalone 模式 | 可用 `default_factory` 创建自有组件 |
### 4.4 Step.Ref
@ -315,23 +322,23 @@ flowchart LR
关键源码行为：
| 源码 | 行为 |
|------------------|-------------------------------------------------|
| 源码 | 行为 |
|------------------|--------------------------------------------------------|
| `_start()` | 把 YAML 中每个 step config 解析成 `(step_cls, params)` |
| `_build_steps()` | 每次调用都创建新的 Step 实例，避免跨请求共享状态 |
| `__call__()` | 创建 `RuntimeContext`，按顺序执行 step |
| 异常处理 | 捕获异常，`response.success=False`，`answer=str(e)` |
| `_build_steps()` | 每次调用都创建新的 Step 实例，避免跨请求共享状态 |
| `__call__()` | 创建 `RuntimeContext`，按顺序执行 step |
| 异常处理 | 捕获异常，`response.success=False`，`answer=str(e)` |
### 6.2 StreamJob
`StreamJob` 继承 `BaseJob`，但返回流式 chunk：
| 行为 | 说明 |
|---------|---------------------------------------------------------|
| context | 带 `stream_queue` |
|-----------|-----------------------------------------------------------|
| context | 带 `stream_queue` |
| Step 输出 | 调用 `context.add_stream_string(text, ChunkEnum.CONTENT)` |
| 异常 | 写入 `ChunkEnum.ERROR` |
| 结束 | 总是发送 `DONE` chunk |
| 结束 | 总是发送 `DONE` chunk |
### 6.3 BackgroundJob
@ -376,7 +383,9 @@ jobs:
```mermaid
flowchart LR
Jobs["default.yaml jobs"] --> BG["background<br/>index_update_loop<br/>resource_watch_loop<br/>digest_watch_loop"]
Jobs --> Base["base<br/>version / help / health_check<br/>search / node_search / traverse / reindex<br/>read / write / edit / delete / move / list / stat<br/>daily_list / daily_reindex / daily_write<br/>auto_memory / auto_resource / auto_dream / proactive"]
Jobs --> Cron["cron<br/>dream_cron<br/>optimize_index_cron"]
Jobs --> Stream["stream<br/>chat"]
Jobs --> Base["base<br/>version / help / health_check / status / app_config<br/>search / node_search / traverse / graph_snapshot / reindex<br/>read / load / read_image / write / save / edit / delete / move / list / stat / frontmatter_*<br/>daily_list / daily_reindex / daily_write<br/>auto_memory / auto_memory_cc / auto_resource / auto_dream / proactive"]
```
## 7. Step 模型
@ -400,12 +409,12 @@ flowchart LR
`RuntimeContext` 是一次 Job 调用内所有 Step 共享的上下文：
| 字段 | 说明 |
|----------------|---------------------------------------------|
| 字段 | 说明 |
|----------------|--------------------------------------------------|
| `response` | 最终返回的 `Response(answer, success, metadata)` |
| `data` | 自由字典，保存输入参数和中间结果 |
| `stream_queue` | 流式 Job 的输出队列 |
| `stop_event` | 后台 Job 的停止信号 |
| `data` | 自由字典，保存输入参数和中间结果 |
| `stream_queue` | 流式 Job 的输出队列 |
| `stop_event` | 后台 Job 的停止信号 |
Step 里常见写法：
@ -468,21 +477,22 @@ flowchart LR
`reme/config/default.yaml` 当前默认组件：
| ComponentEnum | 名称 | backend | 说明 |
|-------------------|---------------------------------|--------------------------------|------------------------------------------------------|
| `service` | 单例 | `http` | 默认 HTTP 服务 |
| `tokenizer` | `default` | `regex` | BM25 分词器 |
| `as_embedding` | `default` | `${EMBEDDING_BACKEND:-openai}` | embedding 模型封装 |
| `embedding_store` | `default` | `local` | embedding 存储，依赖 `as_embedding: default` |
| `as_llm` | `default` | `${LLM_BACKEND:-openai}` | LLM 模型封装 |
| `agent_wrapper` | `default` | `agentscope` | AgentScope wrapper |
| `agent_wrapper` | `claude_code` | `claude_code` | Claude Code wrapper |
| `file_graph` | `default` | `local` | wikilink 图谱 |
| `file_catalog` | `default/resource/digest/dream` | `local` | 文件变更 checkpoint |
| `file_chunker` | `markdown` | `markdown` | Markdown AST 分块 |
| `file_chunker` | `default` | `default` | 默认文本分块，当前支持 `jsonl` |
| `keyword_index` | `default` | `bm25` | BM25 关键词索引 |
| `file_store` | `default` | `local` | 组合 file_graph、keyword_index；默认 `embedding_store: ""` |
| ComponentEnum | 名称 | backend | 说明 |
|-------------------|---------------------------------|-----------------------------|------------------------------------------------------------|
| `service` | 单例 | `http` | 默认 HTTP 服务 |
| `tokenizer` | `default` | `regex` | BM25 分词器 |
| `as_embedding` | `default` | 默认未配置；示例为 `openai` | 取消配置注释后提供 embedding 模型封装 |
| `embedding_store` | `default` | 默认未配置；示例为 `local` | 取消配置注释后依赖 `as_embedding: default` |
| `as_llm` | `default` | `${LLM_BACKEND:-openai}` | LLM 模型封装 |
| `agent_wrapper` | `default` | `agentscope` | AgentScope wrapper |
| `agent_wrapper` | `claude_code` | `claude_code` | Claude Code wrapper |
| `agent_wrapper` | `codex/codex_oauth` | `codex` | 分别使用 API key 与 OAuth 的 Codex wrapper |
| `file_graph` | `default` | `local` | wikilink 图谱 |
| `file_catalog` | `default/resource/digest/dream` | `local` | 文件变更 checkpoint |
| `file_chunker` | `markdown` | `markdown` | Markdown AST 分块 |
| `file_chunker` | `json/jsonl/default` | `json/jsonl/default` | JSON、JSONL 与通用文本分块；默认通用分块支持 `txt`、`log` |
| `keyword_index` | `default` | `bm25` | BM25 关键词索引 |
| `file_store` | `default` | `local` | 组合 file_graph、keyword_index；默认 `embedding_store: ""` |
注意：`search` step 的配置含 `vector_weight`，但默认 `file_store.default.embedding_store` 为空，因此实际是否有向量检索取决于运行配置是否启用
embedding store。
@ -540,12 +550,12 @@ class MySearchStep(BaseStep):
可直接用的常见属性：
| 属性 | 默认解析的组件 |
|----------------------|------------------------------|
| `self.as_llm` | `as_llm: default` 的 `.model` |
| `self.agent_wrapper` | `agent_wrapper: default`，可选 |
| `self.file_catalog` | `file_catalog: default`，可选 |
| `self.file_store` | `file_store: default` |
| 属性 | 默认解析的组件 |
|----------------------|--------------------------------|
| `self.as_llm` | `as_llm: default` 的 `.model` |
| `self.agent_wrapper` | `agent_wrapper: default`，可选 |
| `self.file_catalog` | `file_catalog: default`，可选 |
| `self.file_store` | `file_store: default` |
如果希望 Job 配置指定非 default 组件：
@ -557,13 +567,13 @@ steps:
### 9.4 Step 设计建议
| 建议 | 原因 |
|--------------------------------------------|--------------------------------------------|
| 从 `context` 读取输入，向 `context` 写中间结果 | 多 Step Job 依赖同一个上下文传递数据 |
| 最终结果写到 `context.response` | Service 和 client 只关心标准 `Response` |
| 不在 Step 实例上保存请求级状态 | 每次 Job 调用会重建 Step，但保持无状态更容易测试 |
| 需要中断的后台循环检查 `context.stop_event` | `BackgroundJob.close()` 依赖 stop_event 优雅退出 |
| 流式输出只在 StreamJob 中调用 `add_stream_string()` | 普通 Job 没有 stream queue |
| 建议 | 原因 |
|-----------------------------------------------------|--------------------------------------------------|
| 从 `context` 读取输入，向 `context` 写中间结果 | 多 Step Job 依赖同一个上下文传递数据 |
| 最终结果写到 `context.response` | Service 和 client 只关心标准 `Response` |
| 不在 Step 实例上保存请求级状态 | 每次 Job 调用会重建 Step，但保持无状态更容易测试 |
| 需要中断的后台循环检查 `context.stop_event` | `BackgroundJob.close()` 依赖 stop_event 优雅退出 |
| 流式输出只在 StreamJob 中调用 `add_stream_string()` | 普通 Job 没有 stream queue |
### 9.5 单测示例
@ -721,12 +731,12 @@ jobs:
后台 Job 的特点：
| 特点 | 说明 |
|--------------|----------------------------------------------------|
| 不对外暴露 | `BackgroundJob.__init__()` 强制 `enable_serve=False` |
| 有 supervisor | 默认异常后指数退避重启 |
| 有 stop_event | close 时通知循环退出 |
| 适合监听/消费 | 文件监听、队列消费、周期性长循环 |
| 特点 | 说明 |
|---------------|------------------------------------------------------|
| 不对外暴露 | `BackgroundJob.__init__()` 强制 `enable_serve=False` |
| 有 supervisor | 默认异常后指数退避重启 |
| 有 stop_event | close 时通知循环退出 |
| 适合监听/消费 | 文件监听、队列消费、周期性长循环 |
### 10.5 新增 Cron Job
@ -752,14 +762,14 @@ jobs:
大多数场景只需要新增 Step + YAML Job。只有这些情况才考虑新增 `reme/components/job/*.py`：
| 需求 | 是否需要新 Job 类 |
|----------------|---------------------------|
| 新增一个业务命令 | 否，用 `backend: base` |
| 串联多个已有步骤 | 否，用 `steps:` |
| 要 SSE/流式输出 | 否，用 `backend: stream` |
| 要后台循环 | 否，用 `backend: background` |
| 要 cron 定时 | 否，用 `backend: cron` |
| 要全新的调度/并发/事务语义 | 是，新增 Job backend |
| 需求 | 是否需要新 Job 类 |
|----------------------------|------------------------------|
| 新增一个业务命令 | 否，用 `backend: base` |
| 串联多个已有步骤 | 否，用 `steps:` |
| 要 SSE/流式输出 | 否，用 `backend: stream` |
| 要后台循环 | 否，用 `backend: background` |
| 要 cron 定时 | 否，用 `backend: cron` |
| 要全新的调度/并发/事务语义 | 是，新增 Job backend |
新增 Job backend 的最小形态：

95
docs/zh/memory_as_file.md
View file

@ -6,8 +6,8 @@ ReMe 的核心思想是：**Memory as File, File as Memory**。
<img src="../figure/memory-as-file.svg" alt="ReMe Memory as File 文件化记忆模型" width="92%">
</p>
**Memory as File**：长期记忆不是藏在黑盒数据库里，而是落在 workspace 目录中的 Markdown 文件、资源文件和索引快照里。用户和 Agent
都可以直接读、写、移动、删除这些文件。
**Memory as File**：长期记忆不是藏在黑盒数据库里，原始材料和可读记忆都落在 workspace 内由用户拥有的文件中。用户和 Agent
可以直接读、写、移动、删除它们；`metadata/` 里的索引和快照是可重建的派生状态。
**File as Memory**：每个文件不只是普通文本，也是一个可索引、可链接、可演化的记忆节点。ReMe 会从文件中解析 frontmatter、正文
chunk、wikilink 边，并把它们组织成检索和图谱。
@ -18,14 +18,14 @@ chunk、wikilink 边，并把它们组织成检索和图谱。
ReMe 把记忆设计成文件，不只是为了“方便存储”，而是为了让长期记忆具备几个基本性质：
| 目标 | 含义 |
|----------|----------------------------------------------------------------------|
| 可读 | 用户可以直接打开 workspace，像读普通笔记一样读 daily、digest 和原始材料。 |
| 可编辑 | 用户和 Agent 都能用文件操作修正、补充、移动或删除记忆，不必依赖专用数据库客户端。 |
| 可追溯 | digest 中的长期结论可以通过 Sources 章节回到 daily、resource 或 session 原文。 |
| 可迁移 | workspace 是普通目录，Markdown、JSONL、YAML 和资源文件可以被备份、同步、版本管理或迁移到其他工具。 |
| 可索引 | 文件虽然是普通文本，但 ReMe 会解析 frontmatter、chunk、wikilink，构建检索索引和文件图谱。 |
| 可协作 | 人负责判断和修正，Agent 负责整理、链接和检索；二者看到和操作的是同一套文件。 |
| 目标 | 含义 |
|--------|----------------------------------------------------------------------------------------------------|
| 可读 | 用户可以直接打开 workspace，像读普通笔记一样读 daily、digest 和原始材料。 |
| 可编辑 | 用户和 Agent 都能用文件操作修正、补充、移动或删除记忆，不必依赖专用数据库客户端。 |
| 可追溯 | digest 中的长期结论可以通过 Sources 章节回到 daily、resource 或 session 原文。 |
| 可迁移 | workspace 是普通目录，Markdown、JSONL、YAML 和资源文件可以被备份、同步、版本管理或迁移到其他工具。 |
| 可索引 | 文件虽然是普通文本，但 ReMe 会解析 frontmatter、chunk、wikilink，构建检索索引和文件图谱。 |
| 可协作 | 人负责判断和修正，Agent 负责整理、链接和检索；二者看到和操作的是同一套文件。 |
因此，ReMe 的记忆不是“数据库里的一条隐藏记录”，也不是“只给 LLM 看的 prompt 片段”。它首先是用户拥有的文件，其次才被系统索引成可召回的记忆。
@ -34,7 +34,7 @@ ReMe 把记忆设计成文件，不只是为了“方便存储”，而是为了
ReMe 的 workspace 把记忆分成四层：
```text
raw input -> session/ + resource/
source records -> session/ + resource/
working memory -> daily/
long memory -> digest/
system state -> metadata/
@ -42,13 +42,14 @@ system state -> metadata/
这四层解决的是不同问题。
`session/` 和 `resource/` 保存原始输入。它们强调“不要丢现场”：对话、Agent session、上传资料、网页或报告先原样留下，作为以后核对的证据。
`session/` 和 `resource/` 保存来源记录。`resource/` 文件保持原路径和原内容；标准 Auto Memory 保留对话消息，但会有意排除
tool-result 和 base64 data block，防止召回结果和二进制负载被误当成用户证据。Agent 运行时生成状态则放在 `mem_session/`。
`daily/` 是浅加工层。它把当天发生的对话和资源整理成更适合阅读的 daily note：什么事情发生了、有哪些结论、留下了哪些后续任务、对应原文在哪里。
daily 不追求最终抽象，它更像当天工作台。
`digest/` 是深加工层。这里保存的是可以长期复用的记忆节点，例如用户偏好、项目背景、流程经验、概念知识、决策先例。digest
不应该只是复制 daily，而应该把多次出现的事实、方法和关系合并成更稳定的表述。
`digest/` 是深加工层。这里保存的是可以长期复用的记忆节点，例如用户偏好、项目背景、流程经验、概念知识、决策先例。digest 不应该只是复制
daily，而应该把多次出现的事实、方法和关系合并成更稳定的表述。
`metadata/` 是系统索引层。它保存 file catalog、chunk 索引、图谱快照等运行状态。用户通常不需要手写这里的内容；真正的人工编辑入口是
`daily/`、`digest/` 和必要时的 `resource/`。
@ -60,27 +61,29 @@ daily 不追求最终抽象，它更像当天工作台。
ReMe 用目录表达记忆组织和记忆分层。原始材料先进入 `resource/` 或 `session/`，再沉淀到 `daily/`，最后由 `auto_dream`
整合到 `digest/`。
对应的自动流程分别是 [Auto Memory](./auto_memory.md)、[Auto Resource](./auto_resource.md) 和 [Auto Dream](./auto_dream.md)。
检索这些文件时使用 [Memory Search](./memory_search.md)。
对应的自动流程分别是 [Auto Memory](./auto_memory.md)、[Auto Resource](./auto_resource.md)
和 [Auto Dream](./auto_dream.md)。检索这些文件时使用 [Memory Search](./memory_search.md)。
```text
<workspace_dir>/
├── metadata/ # 系统索引层；ReMe 索引、图谱、catalog 等持久状态，不作为人工编辑入口
├── session/ # 原始输入层；原始对话和 Agent session
├── session/ # 来源记录层；对话来源记录
│ ├── dialog/
│ │ └── <session_id>.jsonl # auto_memory 保存的对话消息
│ ├── agentscope/
│ │ └── <session_id>.jsonl
│ │ └── <session_id>.jsonl # auto_memory 保存的来源消息
│ └── claude_code/
│ └── <session_id>.jsonl
├── resource/ # 原始输入层；外部原始材料
│ └── <session_id>.jsonl # auto_memory_cc 使用的 ReMe 副本
├── mem_session/ # Agent wrapper 生成的 session/配置，不是用户记忆
│ ├── agentscope/
│ ├── claude_config/
│ └── codex/
├── resource/ # 来源记录层；外部原始材料
│ ├── <resource>.<ext> # 根目录文件使用今天日期
│ └── YYYY-MM-DD/
│ └── <resource>.<ext>
│ └── <resource>.<ext> # 按目录日期进入 daily
├── daily/ # 浅加工层；按日期组织当天事实、对话摘要、资源解读
│ ├── YYYY-MM-DD.md # 当天索引页
│ └── YYYY-MM-DD/
│ ├── <session_id>.md # 对话加工后的 daily note
│ ├── <resource_stem>.md # 资源加工后的 daily note
│ ├── <generated_name>.md # 按主题命名的对话或资源卡片
│ └── interests.yaml # auto_dream 产出的主动兴趣主题
└── digest/ # 深加工层；可长期复用的个人事实、流程经验、知识节点
├── personal/
@ -96,17 +99,18 @@ ReMe 用目录表达记忆组织和记忆分层。原始材料先进入 `resourc
```text
对话
-> session/dialog/<session_id>.jsonl
-> daily/YYYY-MM-DD/<session_id>.md
-> daily/YYYY-MM-DD/<generated_name>.md
-> digest/personal | digest/procedure | digest/wiki
外部资料
-> resource/YYYY-MM-DD/<resource>.<ext>
-> daily/YYYY-MM-DD/<resource_stem>.md
-> resource/[YYYY-MM-DD/]<resource>.<ext>
-> daily/YYYY-MM-DD/<generated_name>.md
-> digest/wiki | digest/procedure
```
前两步偏向记录和整理，最后一步偏向长期沉淀。`auto_memory` 和 `auto_resource` 负责从原始输入生成 daily，`auto_dream`
负责从 daily 抽取并整合 digest。
负责从 daily 抽取并整合 digest。daily 文件名来自经校验的 frontmatter `name`；`session_id`、`source_conversation`
和 `source_resource` 负责稳定追溯与定位，不用来强制决定文件名。
## Markdown 格式
@ -158,7 +162,7 @@ confidence: observed
## Sources
- [[daily/2026-06-20/session-a.md]]
该偏好记录于 [[daily/2026-06-20/文档说明风格.md]]，其中保留了用户多次提出的指导。
```
这样做有三个好处：
@ -180,7 +184,7 @@ Wikilink 用 `[[...]]` 表达文件之间的关系：
[[notes/example.md#L9-L10,L15-L20]]
```
ReMe 的 wikilink 是**字面路径语义**：
ReMe 的 wikilink 是 **字面路径语义**：
```text
[[X]] -> target_path = "X"
@ -190,9 +194,9 @@ ReMe 的 wikilink 是**字面路径语义**：
`[label](../wiki/example.md)` 这类普通 Markdown 链接不会建立 `FileLink`，move 或 retarget 操作也不会改写它们。
`#L9`、`#L9-L10` 和 `#L9-L10,L15-L20` 这类锚点会作为普通 `target_anchor` 字符串保存在图谱中。图谱解析器
不会校验行号锚点，因此 `#L0`、`#L10-L9`、`#L9,` 也会被保存。`read` 不会解析追加在 `path` 后的锚点；读取指定
范围时需要分别传入从 1 开始、首尾均包含的 `start_line` 和 `end_line`，例如
`#L9`、`#L9-L10` 和 `#L9-L10,L15-L20` 这类锚点会作为普通 `target_anchor` 字符串保存在图谱中。图谱解析器不会校验行号锚点，因此
`#L0`、`#L10-L9`、`#L9,` 也会被保存。`read` 不会解析追加在 `path` 后的锚点；读取指定范围时需要分别传入从 1 开始、首尾均包含的
`start_line` 和 `end_line`，例如
`read(path="digest/wiki/光伏.md", start_line=9, end_line=10)`。
Wikilink 的作用：
@ -215,8 +219,7 @@ FileLink
旧文档中的 `related:: [[path]]`、`- related:: [[path]]` 或
`[related:: [[path]]]` 仍然可以读取。ReMe 会忽略外围文本，把内部 `[[path]]`
作为普通链接建立索引。从曾存储 typed link 的版本升级后，应执行一次 `reme reindex`，
用源文件重建不含旧关系字段的派生图索引。
作为普通链接建立索引。从曾存储 typed link 的版本升级后，应执行一次 `reme reindex`，用源文件重建不含旧关系字段的派生图索引。
### 来源和关系
@ -227,8 +230,8 @@ Sources 章节说明“这条长期记忆从哪里来”：
```markdown
## Sources
- [[daily/2026-06-20/session-a.md]]
- [[resource/2026-06-20/report.pdf]]
该偏好观察自 [[daily/2026-06-20/文档说明风格.md]]，支撑它的报告证据保留在
[[resource/2026-06-20/report.pdf]] 中。
```
概念关系链接说明“这个节点和哪些长期记忆有关”，并自然织入正文：
@ -243,13 +246,13 @@ Sources 章节说明“这条长期记忆从哪里来”：
因为记忆就是文件，用户可以直接在编辑器里改 workspace；Agent 也可以通过 ReMe 的文件工具读写同一批文件。两者遵守同一套约定：
| 操作 | 建议 |
|--------|--------------------------------------------------------------------|
| 新增记忆 | 写入合适目录，Markdown 使用 frontmatter，并尽量写完整 workspace-relative wikilink。 |
| 修改正文 | 保留已有来源和关键 wikilink；如果是修正旧结论，在正文里说明新材料如何改变旧判断。 |
| 移动文件 | 使用 ReMe 的 move 工具时会默认改写入边中的旧路径；手工移动后建议重新检查入链。 |
| 删除文件 | 删除前检查入链；ReMe 的 delete 会返回仍然指向目标的来源文件，方便清理悬空引用。 |
| 修改元数据 | 用 frontmatter 表达短字段；正文发生实质变化时同步更新 `description`。 |
| 操作 | 建议 |
|------------|-------------------------------------------------------------------------------------|
| 新增记忆 | 写入合适目录，Markdown 使用 frontmatter，并尽量写完整 workspace-relative wikilink。 |
| 修改正文 | 保留已有来源和关键 wikilink；如果是修正旧结论，在正文里说明新材料如何改变旧判断。 |
| 移动文件 | 使用 ReMe 的 move 工具时会默认改写入边中的旧路径；手工移动后建议重新检查入链。 |
| 删除文件 | 删除前检查入链；ReMe 的 delete 会返回仍然指向目标的来源文件，方便清理悬空引用。 |
| 修改元数据 | 用 frontmatter 表达短字段；正文发生实质变化时同步更新 `description`。 |
一个实用规则是：**可以让 Agent 重写表达，但不要让它丢掉证据边**。尤其是 digest 节点中的 Sources 条目和已有
digest-to-digest Wikilink，是长期记忆可追溯和可扩展的基础。
@ -260,7 +263,7 @@ digest-to-digest Wikilink，是长期记忆可追溯和可扩展的基础。
```text
digest/wiki/光伏.md
daily/2026-06-20/session-a.md
daily/2026-06-20/文档说明风格.md
resource/2026-06-20/report.pdf
```

49
docs/zh/memory_search.md
View file

@ -1,7 +1,8 @@
# Memory Search
Memory Search 是 ReMe 的记忆检索入口。它先把 `daily/`、`digest/`、`resource/` 里的文件持续构建成可搜索的 chunk 索引和
wikilink 图谱；查询时先召回最相关的片段，再沿着片段所在文件的双向链接展开上下文。
Memory Search 是 ReMe 的记忆检索入口。默认后台持续把 `daily/`、`digest/` 里的 Markdown 构建成可搜索的 chunk 索引和
wikilink 图谱；查询时先召回最相关的片段，再沿着片段所在文件的双向链接展开上下文。`reme reindex` 的重建范围更宽，会额外扫描
`resource/` 和 JSONL；这与实时 watcher 的默认范围不同。
<p align="center">
<img src="../figure/auto-index-and-memory-search.svg" alt="ReMe Auto Index and Memory Search 索引、召回、融合与链接展开流程" width="92%">
@ -19,14 +20,14 @@ workspace files
## 它搜索什么
默认配置里的 `index_update_loop` 监听三类记忆目录：
默认配置里的 `index_update_loop` 监听两类记忆目录：
- `daily_dir`：Auto Memory 生成的每日工作记忆和 session 记忆卡片。
- `digest_dir`：长期沉淀后的 digest 节点。
- `resource_dir`：外部资源或导入资料。
默认后缀是 `md` 和 `jsonl`。其中 Markdown 用 `markdown` chunker，能解析 frontmatter、标题结构和 `[[wikilink]]`；`jsonl` 用
`default` chunker，按字节大小做重叠切块。
默认实时后缀只有 `md`。`resource_dir` 由独立的 `resource_watch_loop` 监听，并经 Auto Resource 转换成 daily 卡片后进入实时索引。
如果手动运行 `reme reindex`，其配置会扫描 `daily_dir`、`digest_dir`、`resource_dir` 下的 `md` 和 `jsonl`；Markdown 用
`markdown` chunker，JSONL 用 `jsonl` chunker。
## 索引怎么构建
@ -37,8 +38,8 @@ workspace files
```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
@ -67,7 +68,8 @@ Markdown chunker 会解析 YAML frontmatter、标题结构和 wikilink，产出
### 索引优化
BM25 和 FAISS HNSW 向量索引在删除节点时都采用墓碑（tombstone）标记而非物理移除，积累过多会拖慢搜索。为此内置了闲暇时间索引优化机制——`optimize_index_cron` 定时任务在低峰期压缩墓碑并重建索引：
BM25 和 FAISS HNSW 向量索引在删除节点时都采用墓碑（tombstone）标记而非物理移除，积累过多会拖慢搜索。为此内置了闲暇时间索引优化机制——
`optimize_index_cron` 定时任务在低峰期压缩墓碑并重建索引：
```yaml
optimize_index_cron:
@ -94,14 +96,15 @@ file_store:
它组合三类能力：
| 部件 | 默认状态 | 作用 |
|-------------------------|------|--------------------------------------|
| `file_chunks` | 启用 | 保存 `FileChunk` 文本、行号、分数、可选 embedding |
| `keyword_index.default` | 启用 | BM25 倒排索引，chunk id 是 doc id |
| `file_graph.default` | 启用 | 保存 `FileNode` 和 wikilink 边 |
| `embedding_store` | 默认关闭 | 开启后为 chunk 生成 embedding，并支持向量召回 |
| 部件 | 默认状态 | 作用 |
|-------------------------|----------|---------------------------------------------------|
| `file_chunks` | 启用 | 保存 `FileChunk` 文本、行号、分数、可选 embedding |
| `keyword_index.default` | 启用 | BM25 倒排索引，chunk id 是 doc id |
| `file_graph.default` | 启用 | 保存 `FileNode` 和 wikilink 边 |
| `embedding_store` | 默认关闭 | 开启后为 chunk 生成 embedding，并支持向量召回 |
所以开箱搜索主要是 BM25 + 链接展开。把 `embedding_store: default` 打开后，`SearchStep` 会同时跑向量召回和关键词召回。此时若将 `file_store` 的 `backend` 从 `local` 改为 `faiss`，向量检索会从线性扫描升级为 FAISS HNSW 索引，在大规模 chunk 场景下召回效率更高。
所以开箱搜索主要是 BM25 + 链接展开。把 `embedding_store: default` 打开后，`SearchStep` 会同时跑向量召回和关键词召回。此时若将
`file_store` 的 `backend` 从 `local` 改为 `faiss`，向量检索会从线性扫描升级为 FAISS HNSW 索引，在大规模 chunk 场景下召回效率更高。
## 怎么搜索
@ -115,10 +118,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
```
@ -129,11 +134,17 @@ search:
reme search query="最近关于索引的讨论" limit=5
```
`start_date` 和 `end_date` 可以按 `YYYY-MM-DD` 做包含边界的日期过滤：
```bash
reme search query="索引回归" start_date=2026-06-01 end_date=2026-06-20 limit=10
```
`search_step` 的执行顺序是：
```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 融合"]
@ -200,7 +211,7 @@ Memory Search 的“渐进式”不是一次把全库内容塞进结果，而是
典型文本结构：
```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] ==========
...命中的记忆片段...
outlinks (2):
-> digest/indexing.md name="Indexing" description="..."

40
docs/zh/proactive.md
View file

@ -31,10 +31,10 @@ proactive:
参数含义：
| 参数 | 作用 |
|-------------------|----------------------------------------|
| 参数 | 作用 |
|-------------------|-----------------------------------------------------------------|
| `date` | 要读取的日期，格式为 `YYYY-MM-DD`。为空时使用应用时区中的今天。 |
| `include_content` | 是否在 answer 和 metadata 中返回 YAML 原文，默认 `true`。 |
| `include_content` | 是否在 answer 和 metadata 中返回 YAML 原文，默认 `true`。 |
## 输入契约
@ -62,15 +62,15 @@ topics:
成功读取时，`proactive_step` 会在主要 answer 中返回 `summary` 和 `topics`；当 `include_content=true` 时还会返回
`content`。相同的结果字段也会保留在标准 response metadata 中：
| 字段 | 说明 |
|-----------|----------------------------------------|
| `date` | 实际读取的日期。 |
| `path` | `daily/<date>/interests.yaml`。 |
| `topics` | 解析后的 topic 列表。 |
| 字段 | 说明 |
|-----------|-------------------------------------------------|
| `date` | 实际读取的日期。 |
| `path` | `daily/<date>/interests.yaml`。 |
| `topics` | 解析后的 topic 列表。 |
| `content` | YAML 原文；仅在 `include_content=true` 时返回。 |
| `skipped` | 文件不存在时为 `true`。 |
| `error` | 读取或解析异常。 |
| `summary` | 简短摘要。 |
| `skipped` | 文件不存在时为 `true`。 |
| `error` | 读取或解析异常。 |
| `summary` | 简短摘要。 |
文件存在且解析成功时，answer 是结构化数据，例如：
@ -129,20 +129,20 @@ daily notes
职责边界如下。更完整的 Extract、Integrate、Topics、Finish 说明见 [Auto Dream](./auto_dream.md)：
| 模块 | 职责 |
|----------------------|----------------------------------------|
| 模块 | 职责 |
|----------------------|----------------------------------------------|
| `dream_extract_step` | 从 changed daily 输入抽取 topic candidates。 |
| `dream_topics_step` | 去重、筛选并写入 `interests.yaml`。 |
| `proactive_step` | 读取 `interests.yaml`，暴露给上层 Agent。 |
| `dream_topics_step` | 去重、筛选并写入 `interests.yaml`。 |
| `proactive_step` | 读取 `interests.yaml`，暴露给上层 Agent。 |
`proactive` 不修改任何文件，不更新 catalog，也不负责判断是否应该主动打扰用户。它只提供当天主题材料；是否推送、何时推送、用什么语气推送，应由调用方根据产品策略决定。
## 失败模式
| 场景 | 行为 |
|----------------------|--------------------------------------------|
| `interests.yaml` 不存在 | `success=true`，`skipped=true`，`topics=[]`。 |
| YAML 无法读取或解析异常 | `success=false`，answer 返回错误摘要。 |
| YAML 存在但没有合法 topics | `success=true`，`topics=[]`。 |
| 场景 | 行为 |
|----------------------------|-----------------------------------------------|
| `interests.yaml` 不存在 | `success=true`，`skipped=true`，`topics=[]`。 |
| YAML 无法读取或解析异常 | `success=false`，answer 返回错误摘要。 |
| YAML 存在但没有合法 topics | `success=true`，`topics=[]`。 |
因此推荐调用方先检查 `success`，再检查 `skipped`，最后检查 `topics` 是否为空。

25
docs/zh/quick_start.md
View file

@ -50,10 +50,15 @@ reme start service.port=8181
```bash
reme version
reme health_check
reme list
reme help
```
`reme list` 会列出服务端 action。普通命令会通过 HTTP 调用服务端 Job。
`reme help` 会列出服务端 action。普通命令会通过 HTTP 调用服务端 Job。
如果安装包中包含 Web 构建产物，浏览器打开 <http://127.0.0.1:2333/> 即可进入 ReMe Studio，在同一服务中浏览、编辑和搜索
workspace，并查看 digest Wikilink 图。可用 `service.web_enabled=false` 关闭，或通过 `service.web_static_dir` /
`REME_WEB_STATIC_DIR`
指定自定义静态目录；找不到构建产物时，Job API 仍会正常启动。
---
@ -64,7 +69,8 @@ reme list
```text
.reme/
├── metadata/ # 索引、图谱、catalog 等持久状态
├── session/ # Agent session 与原始对话
├── session/ # 对话来源记录
├── mem_session/ # Agent wrapper 生成的 session/配置
├── resource/ # 外部资料
├── daily/ # daily note
└── digest/ # 长期记忆
@ -89,7 +95,7 @@ reme write \
description="快速开始示例记忆" \
content="# Quick Start Demo
ReMe 会索引 daily、digest 和 resource 目录中的 Markdown。
默认实时 watcher 会索引 daily 和 digest 目录中的 Markdown。
相关链接：[[digest/wiki/search-demo.md]]"
```
@ -128,7 +134,13 @@ reme frontmatter_read path=digest/wiki/quick-start-demo
reme frontmatter_update path=digest/wiki/quick-start-demo metadata='{"tags":["demo"]}'
```
`list` 这个名字在 CLI 中用于 action 列表，所以文件列表 Job 需要用 HTTP 调：
文件列表 Job 可以直接通过 CLI 调用：
```bash
reme list path=digest recursive=true limit=50
```
等价的 HTTP 调用是：
```bash
curl -s http://127.0.0.1:2333/list \
@ -157,7 +169,8 @@ reme auto_memory \
memory_hint="记录用户偏好"
```
外部资料放入 `resource/YYYY-MM-DD/` 后，默认后台会监听 `md/txt/json/jsonl/csv/yaml/html`。也可以手动触发：
外部资料放入 `resource/YYYY-MM-DD/` 或直接放在 `resource/` 下后，默认后台会监听 `md/txt/json/jsonl/csv/yaml/html`。
也可以手动触发：
```bash
reme auto_resource changes='[{"path":"resource/2026-06-20/report.md","change":"added"}]'

28
docs/zh/reme-blog.md
View file

@ -75,7 +75,7 @@ kind: preference
## Sources
- [[daily/2026-08-07/content-discussion.md]]
该偏好观察自 [[daily/2026-08-07/content-discussion.md]]，其中记录了用户对写作方式的要求。
```
几个月后，即使你已经忘了这次对话，Agent 仍然能读到偏好、找到关联流程，并顺着 `Sources` 回到当时的上下文。
@ -95,14 +95,17 @@ kind: preference
> “这周先不要重构登录模块，客户演示之后再做。上次直接升级依赖导致兼容问题，这次先补回归测试。”
这段话里同时包含了项目状态、时间约束、一次失败经验和后续行动。Auto Memory 会把它从聊天流水中提炼出来，写成当天的一张 daily
记忆卡片；原始对话则继续保存在 `session/dialog/` 中。
记忆卡片；可追溯的对话来源记录则保存在 `session/dialog/` 中。
```text
session/dialog/project-a.jsonl 原始对话，负责保留现场
daily/2026-08-07/project-a.md 记忆卡片，负责好读
daily/2026-08-07.md 当天索引，负责总览
session/dialog/project-a.jsonl 对话来源记录
daily/2026-08-07/login-refactor-decision.md 按内容命名的记忆卡片
daily/2026-08-07.md 当天索引，负责总览
```
`session_id` 仍保留在卡片 frontmatter 中，用于稳定定位和追溯；文件名来自 Agent 生成的主题/事件 `name`，不必与 session ID
相同。
以后再讨论登录模块，Agent 不必翻遍聊天记录，就能先看到：当前为什么没有重构、曾经踩过什么坑、下一步应该先做什么。
它像一位一直在场的记录者，但不是机械地抄写逐字稿，而是把“以后还会用到什么”整理出来。
@ -145,7 +148,8 @@ Daily Paper 展示了 Auto Resource 可以怎样被组合成具体工作流，
- 第二次在项目文档中确认根因是 Node 内存不足；
- 第三次又补充了大型 TypeScript 项目下更容易触发这个问题。
Auto Dream 会扫描所有发生变化的 daily 文件，合并指向同一抽象的证据，只保留值得复用的记忆单元，再按内容写入三类长期记忆：
Auto Dream 默认查看以目标日期结尾的最近两天，只把相对上次运行发生变化的 daily 文件一起交给抽取器。它合并指向同一抽象的跨文件
证据，并在默认最多五个 unit 的额度内只保留最值得复用的记忆，再按内容写入三类长期记忆：
- `Personal`：用户、团队或项目特定的偏好、约定和约束；
- `Procedure`：可以再次执行的流程、方法和排查手册；
@ -168,7 +172,7 @@ Auto Dream 会扫描所有发生变化的 daily 文件，合并指向同一抽
## Sources
- [[daily/2026-08-07/build-debug.md|构建排查记录]] 提供了根因与适用场景。
根因与适用场景记录在 [[daily/2026-08-07/build-debug.md|构建排查记录]] 中。
```
知识的演化与链接发生在同一条流程里。关系不是藏在图数据库里的不可见边，而是正文中可读、可改的内容；文件可以重建图，图不会反过来绑架文件。
@ -179,8 +183,9 @@ Auto Dream 会扫描所有发生变化的 daily 文件，合并指向同一抽
<img src="../figure/reme-blog/reme-blog-memory-index.svg" alt="ReMe Memory Index 构建过程" width="100%">
</p>
Markdown 适合人读，但如果只是把文件堆进目录，Agent 仍然很难快速找到它们。ReMe 会持续监听 `daily/`、`digest/` 和 `resource/`，
将新增、修改和删除同步到可重建的索引中。
Markdown 适合人读，但如果只是把文件堆进目录，Agent 仍然很难快速找到它们。默认实时索引持续监听 `daily/` 与 `digest/` 中的
Markdown；`resource/` 由独立资源流程监听，转成 daily 卡片后进入同一索引。需要从现有文件完整重建时，`reme reindex` 还会扫描
`resource/` 与 JSONL。
一份 Markdown 会被解析为：
@ -323,8 +328,9 @@ ReMe 给出的答案很朴素：
## 接入你正在使用的 Agent
ReMe 既可以作为本地记忆服务，通过 CLI、HTTP API 或 MCP Server 接入，也可以通过 Python API 嵌入宿主进程。不同 Agent
可以选择适合自身运行环境的路径，并按需共享同一个本地 memory workspace。
ReMe 既可以作为本地记忆服务，通过 CLI、HTTP API 或 MCP Server 接入，也可以通过 Python API 嵌入宿主进程。默认 HTTP
服务还可在同一地址提供 ReMe Studio，用于浏览、编辑、搜索 workspace 和查看 digest Wikilink 图。不同 Agent 可以选择适合自身
运行环境的路径，并按需共享同一个本地 memory workspace。
| Agent | 推荐接入方式 | 接入后能力 |
|----------------------------------------|--------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------|

36
docs/zh/reme_scene.md
View file

@ -50,18 +50,20 @@ 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 # auto_dream 后生成
```
对应链路：
- `auto_memory` 保存原始对话到 `session/dialog/<session_id>.jsonl`，再让 Agent 把重要事实写入 `daily/<date>/<session_id>.md`。
- `resource_watch_loop` 监听 `resource/` 文本文件变化，并触发 `auto_resource_step` 写同名 daily note。
- `daily_create` 会维护 `daily/<date>.md` 当天索引页。
- `auto_memory` 保存对话来源消息到 `session/dialog/<session_id>.jsonl`，再让 Agent 把重要事实写入按主题命名的
`daily/<date>/<generated_name>.md`；卡片 frontmatter 保留 `session_id` 和 `source_conversation` 用于稳定定位和追溯。
- `resource_watch_loop` 监听 `resource/` 文本文件变化，并触发 `auto_resource_step` 写带 `source_resource` 的 daily note；文件名由
Agent 根据内容建议，再由系统清洗并处理冲突，不保证与资源同名。
- Auto Memory、Auto Resource 和 Auto Dream 都会在写入后刷新 `daily/<date>.md` 当天索引页。
### Day 1 晚上：Auto Dream 进入 Digest
@ -75,8 +77,8 @@ reme auto_dream date=2026-05-18
```text
dream_extract_step
扫描 daily/2026-05-18.md 和 daily/2026-05-18/ 下 changed 文件
输出 units 和 topics
默认扫描 2026-05-17 至 2026-05-18 的 daily 窗口
从 changed 文件输出最多 5 个 units 和 topics
dream_integrate_step
每个 unit 用 node_search 召回已有 digest 节点
@ -114,12 +116,12 @@ description: 锂电正极材料关键原料，主产区集中于刚果(金)
## 供给端
嘉能可三季度钴产量同比下滑 18%，需要继续跟踪供给收缩对价格的影响。
## Sources
- [[daily/2026-05-18/2026-05-18-close.md]]
## 政策风险
刚果(金)矿权政策变化可能影响 KFM 矿运营，需联动跟踪洛阳钼业。
## Sources
产量下滑与政策风险的证据记录在 [[daily/2026-05-18/cobalt-supply-risk.md]] 中。
```
注意：wikilink 是字面路径语义，推荐写完整 workspace-relative 路径和 `.md` 扩展名。ReMe 不会自动把 `[[钴]]` 解析成某个文件。
@ -227,7 +229,7 @@ topics:
reason: 用户当天多次提到 KFM 矿和钴价风险
keywords: [钴, 刚果金, 洛阳钼业, KFM]
paths:
- daily/2026-05-18/2026-05-18-close.md
- daily/2026-05-18/cobalt-supply-risk.md
```
调用：
@ -311,7 +313,7 @@ description: build 卡住且内存上涨时，优先检查类型检查进程内
## Sources
- [[daily/2026-03-10/build-oom-2026-03-10.md]]
失败尝试和有效的内存调整记录在 [[daily/2026-03-10/build-oom-2026-03-10.md]] 中。
```
示例 `digest/personal/code-style.md`：
@ -363,7 +365,7 @@ Agent 回复可以直接跳过低价值路径：
- `digest/procedure/` 保存“怎么做”和“哪些路径无效”，让 Agent 复用排查经验。
- `digest/personal/` 保存用户偏好，让 Agent 跨会话遵守同一工程风格。
- 原始对话仍在 `session/dialog/`，daily 记录可追溯，digest 只是长期提炼结果。
- 对话来源记录仍在 `session/dialog/`，daily 记录可追溯，digest 只是长期提炼结果。
## 场景三：个人第二大脑
@ -410,7 +412,7 @@ description: 用户朋友，常推荐阅读材料
## Sources
- [[daily/2026-04-20/lunch-with-alice.md]]
这次推荐记录在 [[daily/2026-04-20/lunch-with-alice.md]] 中。
```
### 一次联想式回忆

2
plugins/claude_code/reme/.claude-plugin/plugin.json
View file

@ -6,7 +6,7 @@
"name": "EconML team of Alibaba Tongyi Lab",
"email": "jinli.yl@alibaba-inc.com"
},
"homepage": "https://reme.agentscope.io/",
"homepage": "https://docs.agentscope.io/reme",
"repository": "https://github.com/agentscope-ai/ReMe",
"license": "Apache-2.0",
"keywords": ["memory", "reme", "mcp", "long-term-memory", "agent"]

2
pyproject.toml
View file

@ -68,7 +68,7 @@ full = [
[project.urls]
Homepage = "https://github.com/agentscope-ai/ReMe"
Documentation = "https://reme.agentscope.io/"
Documentation = "https://docs.agentscope.io/reme"
Repository = "https://github.com/agentscope-ai/ReMe"
[project.scripts]

17
skills/reme_memory/SKILL.md
View file

@ -5,8 +5,10 @@ description: Set up and use ReMe as a file-native long-term memory system throug
# ReMe Memory
Use ReMe as the persistent memory layer for this Agent. ReMe stores raw sessions, daily notes, resources, and long-term
digest memories in a user-owned local workspace.
Use ReMe as the persistent memory layer for this Agent. ReMe stores filtered conversation source records, daily notes,
resources, and long-term digest memories in a user-owned local workspace. `auto_memory` omits recalled tool results and
base64 data when it persists a source record so retrieved or binary content does not become conversation source
material.
## Bootstrap ReMe
@ -119,7 +121,7 @@ reme version
reme health_check
```
Proceed only when `version` responds and `health_check` reports a healthy service. Use `reme list` to inspect the jobs
Proceed only when `version` responds and `health_check` reports a healthy service. Use `reme help` to inspect the jobs
exposed by the running configuration. If verification fails, report the exact error and keep installation failure,
service discovery failure, port conflict, and missing model credentials as separate diagnoses.
@ -132,13 +134,16 @@ long-term context, search ReMe first:
reme search query="<question or keywords>" limit=5
```
Read the relevant result rather than relying only on the search snippet:
Read a relevant Markdown result rather than relying only on the search snippet:
```bash
reme read path="<workspace-relative-path>"
reme read path="<workspace-relative-path>" start_line=1 end_line=80
```
`read` accepts Markdown only. For a non-Markdown text result, use `reme load path="<workspace-relative-path>"`; because
`load` returns the complete file, inspect its size with `reme stat` first when the file may be large.
Use `traverse` when wikilink neighbors may matter:
```bash
@ -176,8 +181,8 @@ Use ReMe commands instead of editing memory files directly unless the user expli
## Ingest Resources
Place external documents under `resource/YYYY-MM-DD/` in the selected ReMe workspace. The default background watcher
processes supported new or changed files while `reme start` is running.
Place external documents under `resource/YYYY-MM-DD/` in the selected ReMe workspace. While `reme start` is running, the
default background watcher processes new or changed `md`, `txt`, `json`, `jsonl`, `csv`, `yaml`, and `html` files.
To request processing explicitly:

61
website/README.md
View file

@ -1,17 +1,44 @@
# ReMe Studio
Local web studio for browsing ReMe files, editing and previewing Markdown,
exploring memory graphs, and streaming conversations with the ReMe Agent.
English | [简体中文](./README_ZH.md)
ReMe Studio is the local web workspace for ReMe. It lets you browse and edit user-owned workspace files, explore memory
links, and chat with the ReMe Agent without moving durable memory into a separate application database. Search indexes,
graphs, and other derived metadata remain rebuildable from the source files.
![ReMe Studio workspace](./public/og.png)
## Features
- **Workspace browsing**: browse the full workspace or focus on journal and knowledge files through dedicated views. The
navigator refreshes as files change on disk.
- **Markdown editing and preview**: open multiple files in tabs, render Markdown front matter and GitHub Flavored
Markdown, edit with Monaco, save with optimistic modification-time checks, and download files locally.
- **Memory graph**: inspect indexed wikilinks under the `wiki`, `personal`, and
`procedure` knowledge roots, follow inbound and outbound links, and open the corresponding Markdown source.
- **Agent chat**: stream conversations with the read-only workspace Agent, see tool calls and token usage, and drag
workspace files into the conversation as references.
- **Service management**: inspect service and component memory usage, review the effective redacted configuration and
version, and rebuild derived indexes without modifying source memory files.
- **Personalization**: switch between English and Chinese, and use light, dark, or system appearance.
## Requirements
- Node.js 22.13 or newer.
- Python 3.11 or newer with ReMe installed.
- A running ReMe HTTP service. Agent chat additionally requires a working Agent and model configuration.
See the [repository README](../README.md) for ReMe installation and backend configuration.
## Development
Requirements: Node.js 22.13+ and a running ReMe HTTP service.
Start ReMe from the repository root, then run the frontend in another terminal:
```bash
# From the repository root, start ReMe in one terminal.
# Terminal 1, from the repository root
reme start
# Start the web interface in another terminal.
# Terminal 2
cd website
npm install
npm run dev
@ -26,8 +53,7 @@ NEXT_PUBLIC_REME_API_URL=http://127.0.0.1:8000 npm run dev
## ReMe-hosted static build
ReMe can serve the same workspace from its FastAPI process. Build the static
variant and restart ReMe:
ReMe can serve Studio from the same FastAPI process as its HTTP API. Build the static variant and restart ReMe:
```bash
cd website
@ -37,27 +63,30 @@ cd ..
reme start
```
Open <http://127.0.0.1:2333>. The static build uses same-origin requests by
default. For standalone static development, run `npm run dev:static` and set
Open <http://127.0.0.1:2333>. The static build uses same-origin requests by default. For standalone static development,
run `npm run dev:static` and set
`VITE_REME_API_URL` to the running ReMe service URL when necessary.
The regular `npm run build` command remains the vinext/Sites deployment build;
`npm run build:static` creates `dist-static/` exclusively for FastAPI and Python
package distribution.
`npm run build:static` creates `dist-static/` exclusively for FastAPI and Python package distribution.
The workspace hides dotfiles and dot-directories. It displays only Markdown and
text files by default. Configure the allowed extensions as a comma-separated
list in `.env.local`:
## Configuration
The workspace hides dotfiles and dot-directories. It displays only Markdown and text files by default. Configure the
allowed extensions as a comma-separated list in `.env.local`:
```bash
NEXT_PUBLIC_REME_WORKSPACE_EXTENSIONS=md,txt,mdx
```
Useful checks:
The memory graph requires an index built by ReMe. Rebuilding the index from the Studio settings regenerates derived data
from workspace files and does not modify the source memory.
## Checks
```bash
npm run format:check
npm run lint
npx tsc --noEmit
npm run build
npm run build:static
npm test

85
website/README_ZH.md Normal file
View file

@ -0,0 +1,85 @@
# ReMe Studio
[English](./README.md) | 简体中文
ReMe Studio 是 ReMe 的本地 Web 工作区。你可以在这里浏览和编辑自己拥有的工作区文件、探索记忆之间的联系，并与 ReMe Agent
对话，而无需将持久记忆迁移到独立的应用数据库中。搜索索引、图谱和其他派生元数据均可根据源文件重建。
![ReMe Studio 工作区](./public/og.png)
## 功能
- **浏览工作区**：浏览完整工作区，或通过独立视图聚焦日记和知识文件；磁盘中的文件发生变化后，导航器会自动刷新。
- **Markdown 编辑与预览**：在多个标签页中打开文件，渲染 Markdown front matter 和 GitHub Flavored Markdown，使用 Monaco
编辑器编辑，通过修改时间检查安全保存，并可将文件下载到本地。
- **记忆图谱**：查看知识库 `wiki`、`personal` 和 `procedure` 目录中已索引的 wikilink，检查入链和出链，并从图谱打开对应的
Markdown 源文件。
- **Agent 对话**：与只读工作区 Agent 进行流式对话，查看工具调用和 token 用量，还可将工作区文件拖入对话作为引用。
- **服务管理**：查看服务及组件的内存使用情况、当前生效的脱敏配置和版本，并在不修改记忆源文件的情况下重建派生索引。
- **个性化设置**：切换中英文界面，并使用浅色、深色或跟随系统的外观。
## 环境要求
- Node.js 22.13 或更高版本。
- Python 3.11 或更高版本，并已安装 ReMe。
- 正在运行的 ReMe HTTP 服务。Agent 对话还需要可用的 Agent 和模型配置。
ReMe 的安装和后端配置请参阅[仓库中文 README](../README_ZH.md)。
## 本地开发
先在仓库根目录启动 ReMe，然后在另一个终端运行前端：
```bash
# 终端 1：仓库根目录
reme start
# 终端 2
cd website
npm install
npm run dev
```
打开 <http://localhost:3000>。前端默认连接 `http://127.0.0.1:2333`，需要时可覆盖该地址：
```bash
NEXT_PUBLIC_REME_API_URL=http://127.0.0.1:8000 npm run dev
```
## 由 ReMe 托管的静态构建
ReMe 可以通过提供 HTTP API 的同一个 FastAPI 进程托管 Studio。构建静态版本并重启 ReMe：
```bash
cd website
npm ci
npm run build:static
cd ..
reme start
```
打开 <http://127.0.0.1:2333>。静态构建默认使用同源请求。进行独立的静态开发时，运行
`npm run dev:static`；如有需要，将 `VITE_REME_API_URL` 设置为正在运行的 ReMe 服务地址。
常规的 `npm run build` 命令仍用于 vinext/Sites 部署构建；`npm run build:static` 仅为 FastAPI 和 Python 包分发生成
`dist-static/`。
## 配置
工作区会隐藏点文件和点目录，并且默认只显示 Markdown 和文本文件。可以在 `.env.local` 中通过逗号分隔的列表配置允许显示的扩展名：
```bash
NEXT_PUBLIC_REME_WORKSPACE_EXTENSIONS=md,txt,mdx
```
记忆图谱依赖 ReMe 构建的索引。在 Studio 设置中重建索引时，只会根据工作区文件重新生成派生数据，不会修改记忆源文件。
## 检查
```bash
npm run format:check
npm run lint
npm run build
npm run build:static
npm test
```

BIN
website/public/og.png
View file

Binary file not shown.
Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 1.3 MiB

After

Width:  |  Height:  |  Size: 1.5 MiB