scriptoriumadmin/ReMe
1
0
Fork 0
mirror of https://github.com/agentscope-ai/ReMe.git synced 2026-10-14 04:12:05 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 7
ReMe/docs/en/operations.md
Ziyang Guo 1b3319e63a docs(operations): explain that reindex cannot refresh stale chunks 
#524 reports that persisted chunks survive a chunker change and are never
re-chunked. Maintainers closed #528 with the position that automatic
invalidation stays out of scope and the recovery path is to clear derived
state and let the watchers rescan, but that path was only described in the
issue thread. The operations guide already warned that reindex does not
rechunk; add the missing half: reindex reuses stored chunks as-is, so a
chunker change requires the re-chunk recovery instead.
2026-10-01 01:12:10 +08:00

4.1 KiB
Raw Blame History

title description
Diagnostics, Backup, and Recovery ReMe health checks, logs, index maintenance, workspace backup, migration, and recovery.

Diagnostics, Backup, and Recovery

ReMe recovery protects user-owned workspace files and rebuilds catalogs, indexes, and graphs from those sources. Never delete or rewrite user memory merely to repair derived state.

Quick diagnosis

Run these in order:

reme find_reme
reme version
reme health_check
reme status
reme app_config
  • find_reme confirms the actual host, port, and PID;
  • version verifies that the CLI reaches the service;
  • health_check reports component health;
  • status estimates stateful component memory and process RSS;
  • app_config returns the effective configuration with secrets redacted.

Logs and common symptoms

log_to_console and log_to_file control logging. For startup failures, inspect the first exception rather than later client connection errors.

Symptom Check first
CLI cannot find ReMe reme find_reme, process state, startup directory, and port
Automatic memory fails LLM backend, model, API key, and base URL
Search is BM25-only Whether an embedding store is connected to file_store
New files are absent Directory, extension, watcher, and health_check
Studio fails but API works Installed web extra, static path, and browser console
Installed plugin is unavailable Python interpreter, plugins configuration, and service restart

Index maintenance

reme reindex scope=all
reme reindex scope=bm25
reme reindex scope=embedding

reindex rebuilds BM25 and/or embedding indexes from the current file_chunks. It does not scan the workspace, rechunk files, or rebuild the wikilink graph. Diagnose the watcher first when ingestion is the problem.

reindex also keeps whatever chunks are already stored. When the chunking behavior itself changes — an upgraded ReMe or edited chunker settings — the stored chunks are reused as they are, so a plain reindex cannot refresh them. Re-chunk from the source files instead by clearing the derived chunk state and letting the watchers rescan; see Recover derived state. Source files are never modified by this recovery.

Rebuild a daily index page separately:

reme daily_reindex date=2026-09-04

Backup

Stop writes or stop the service, then back up the complete workspace. The most important sources are:

  • session/ for conversation sources;
  • resource/ for external resources;
  • daily/ for daily memory;
  • digest/ for consolidated memory.

metadata/ contains indexes, graphs, and catalogs. Backing it up accelerates restoration, but it is not the sole source of truth.

Use an explicit, stable absolute workspace_dir for durable deployments rather than relying on an incidental .reme/ under the current directory.

Migrate a workspace

  1. Stop the old service to prevent writes during the copy.
  2. Copy the complete workspace while preserving timestamps.
  3. Start with the new absolute path:
reme start workspace_dir=/new/location/reme-memory
  1. Run health_check, status, and a representative search.
  2. Rebuild embeddings if their model or dimensions changed.

Do not push a workspace containing private conversations to a public repository.

Recover derived state

Do not remove anything until a backup exists. Then:

  1. preserve session/, resource/, daily/, and digest/;
  2. record the effective configuration and component backends;
  3. verify that the failure is limited to metadata/;
  4. move suspect derived state to an isolated backup location;
  5. restart with the same configuration and let watchers rebuild;
  6. validate search, graph traversal, and daily indexes.

The internal layout of metadata files is not a public automation contract.

Concurrent editing

When Studio or an editor saves a complete file, pass the mtime from stat as save.expected_mtime. A save then fails if another actor changed the file after it was opened, avoiding silent overwrites.

File Jobs enforce workspace containment and per-path locking. Do not bypass them to write arbitrary absolute paths.