reme-memory

name	reme_memory
description	Set up and use ReMe as a file-native long-term memory system through the reme CLI. Use when an Agent needs to detect whether ReMe is installed or running, install and configure ReMe, start or verify its local service, retrieve prior context, or write and consolidate durable memory.

ReMe Memory

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

Run this workflow before first use and whenever a ReMe command cannot reach the service. Distinguish a missing CLI from an installed but stopped service.

1. Check whether ReMe is installed

Run:

command -v reme

If this prints an executable path, treat ReMe as installed and continue to service discovery. Do not reinstall or upgrade an existing installation unless the user requests it.

If the command is missing, check Python before installing:

python3 -c 'import sys; print(sys.version); raise SystemExit(0 if sys.version_info >= (3, 11) else 1)'

ReMe requires Python 3.11 or newer. If the user has requested setup or installation, install the recommended package in the active Python environment:

python3 -m pip install "reme-ai[core]"

When working from a ReMe source checkout and the user explicitly wants an editable source installation, run this from the repository root instead:

python3 -m pip install -e ".[core]"

Do not silently install into or modify a Python environment when the user only asked to use memory. Explain that ReMe is missing and ask before installing. After installation, run command -v reme again. If it is still missing, check that the active environment's executable directory is on PATH; do not repeatedly reinstall.

2. Configure optional model credentials

Basic file operations, BM25 search, wikilink traversal, and reading existing proactive topics work without model credentials. auto_memory, auto_resource, and auto_dream require an LLM configuration.

When those model-powered jobs are needed, have the user provide valid values through the environment or a .env file:

LLM_API_KEY=sk-xxx
LLM_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1

The default LLM backend is OpenAI-compatible and the default model is qwen3.7-plus. Override them when the endpoint requires different values:

LLM_BACKEND=openai
LLM_MODEL_NAME=qwen3.7-plus

ReMe searches for .env in the directory where its command starts and up to five parent directories. Start the service from a stable directory where the intended .env is discoverable. Never expose, log, or commit credentials.

Embedding retrieval is disabled by default. Do not request EMBEDDING_API_KEY merely to use the default BM25 and wikilink search. Enabling vector retrieval also requires changing the embedding components in ReMe's configuration; do not claim that setting an embedding key alone enables it.

3. Discover or start the service

Check for an existing ReMe service before starting another one:

reme find_reme

If it prints HOST=... PORT=... PID=..., reuse that service and its workspace. Do not start a duplicate or change its workspace configuration.

If it reports reme not started, start ReMe in a persistent terminal or managed process and leave it running:

reme start

The default HTTP address is 127.0.0.1:2333, and the default workspace is .reme/ under the startup directory. For durable Agent memory, prefer a stable, user-selected workspace path so memory does not depend on the caller's current directory:

reme start workspace_dir="/absolute/path/to/reme-workspace"

If port 2333 is occupied, do not stop or replace the unknown listener. Start ReMe on another port:

reme start workspace_dir="/absolute/path/to/reme-workspace" service.port=8181

Keep the startup command and workspace choice consistent across restarts. ReMe CLI commands discover a locally running ReMe process, including one started with a custom port.

4. Verify readiness

After the service starts, run these commands from another terminal or tool session:

reme find_reme
reme version
reme health_check

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.

Retrieve Memory

Before answering questions about previous conversations, user preferences, project history, decisions, resources, or long-term context, search ReMe first:

reme search query="<question or keywords>" limit=5

Read a relevant Markdown result rather than relying only on the search snippet:

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:

reme traverse path="<workspace-relative-path>" depth=1 direction=both

Cite the workspace-relative paths used. If retrieval returns nothing useful, say so plainly instead of inventing prior context.

Write Memory

Record durable facts, user preferences, important decisions, project context, and lessons learned. Avoid secrets or sensitive personal data unless the user explicitly asks to store them.

For an ordinary conversation, call auto_memory with the current messages and a stable session ID:

reme auto_memory \
  session_id="<session-id>" \
  messages='[{"role":"user","content":"..."},{"role":"assistant","content":"..."}]' \
  memory_hint="<why this should be remembered>"

This job requires the LLM configuration described above. A missing LLM credential is not evidence that basic ReMe file operations or BM25 retrieval are unavailable.

For explicit file operations, read before editing and preserve existing content unless replacement is intended:

reme write path="daily/<YYYY-MM-DD>/<name>.md" name="<name>" description="<description>" content="<markdown>"
reme edit path="<workspace-relative-path>" old="<old text>" new="<new text>"

Use ReMe commands instead of editing memory files directly unless the user explicitly asks for direct file maintenance.

Ingest Resources

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:

reme auto_resource changes='[{"path":"resource/<YYYY-MM-DD>/<file>","change":"added"}]'

auto_resource requires LLM credentials.

Consolidate and Use Proactive Topics

The default service runs background and cron jobs while it remains active. auto_dream consolidates daily notes and resource interpretations into long-term digest memory and generates interest topics. Run it manually when the host owns the schedule or the user requests consolidation:

reme auto_dream date="<YYYY-MM-DD>"

Read generated topics with:

reme proactive date="<YYYY-MM-DD>"

auto_dream requires LLM credentials. proactive reads existing structured topics and works without an LLM call. Pass include_content=false when raw YAML content is unnecessary. The host Agent decides whether and how to mention topics; ReMe does not independently notify the user or take external action.

Integration Rules

• Reuse a healthy running service; never start one ReMe process per command or conversation.
• Keep one stable workspace for contexts that should share memory. Use separate workspaces when profiles must be isolated.
• Call auto_memory after useful conversation turns only when the host owns lifecycle integration.
• Use ReMe's in-process ReMe Python API instead of the CLI when embedding it into a Python host application.
• Prefer the dedicated integrations under integrations/claude_code/reme and integrations/hermes_agent for those hosts.
• Treat user-owned memory files as source data. Do not delete, rewrite, or migrate a workspace merely to repair an index; use rebuildable index operations such as reme reindex when appropriate.