ReMe/docs/cli/quick_start_en.md

ReMe CLI Quick Start

Memory Management: Why Does AI Need This?

Anyone who has used LLMs knows the context window is limited. As conversations grow longer:

• The conversation gets cut off and can't continue
• Response quality drops noticeably — it forgets what was said earlier
• Start a new conversation? Everything from before is gone, back to square one

Worse, even if the context isn't full, a new conversation starts as a blank slate. The technical decisions you made last time, your personal preferences, work left half-done — all gone.

ReMe solves this with two capabilities:

Capability	Purpose
Context compaction	When conversations get too long, old content is automatically condensed into summaries to free up space for new content
Long-term memory	Important information is persisted to disk and automatically retrieved in future conversations

---

File-Based Memory Design

ReMe's long-term memory doesn't depend on an external database — Markdown files are the memory itself. You can open and edit them at any time.

Memory design inspired by the OpenClaw memory architecture.

File Structure

.reme/
├── MEMORY.md
└── memory/
    ├── 2025-02-12.md
    ├── 2025-02-13.md
    └── ...

MEMORY.md — Long-Term Memory

Stores key information that rarely changes — essentially your "profile":

• Location: {working_dir}/MEMORY.md
• Example content: Project uses Python 3.12, prefers pytest, database is PostgreSQL
• Written by: Agent maintains it automatically via write / edit tools

memory/YYYY-MM-DD.md — Daily Logs

One file per day, append-only, recording what happened:

• Location: {working_dir}/memory/YYYY-MM-DD.md
• Example content: Fixed login bug, deployed v2.1, discussed caching strategy
• Written by: Agent tool writes + triggered automatically during compaction

---

ReMeCli Demo

---

Installation

PyPI (Recommended)

pip install reme-ai==0.3.0.0b1

From Source

git clone https://github.com/agentscope-ai/ReMe.git
cd ReMe
pip install -e .

Python >= 3.10

---

Configuration

Environment Variables

In addition to the yaml config file, API keys are set via environment variables. You can put them in a .env file at the project root:

Variable	Description	Example
REME_LLM_API_KEY	LLM API Key	sk-xxx
REME_LLM_BASE_URL	LLM Base URL	https://dashscope.aliyuncs.com/compatible-mode/v1
REME_EMBEDDING_API_KEY	Embedding API Key	sk-xxx
REME_EMBEDDING_BASE_URL	Embedding Base URL	https://dashscope.aliyuncs.com/compatible-mode/v1

If you don't have an embedding service, search quality will be reduced. Make sure to also set vector_enabled=false.

Web Search (Optional)

Variable	Description
TAVILY_API_KEY	Tavily Search API Key
DASHSCOPE_API_KEY	DashScope LLM (with search) API Key

Pick one. If Tavily is available, it takes priority.

---

Config File: cli.yaml

remecli loads cli.yaml on startup ( config_path="cli"). All core parameters are managed in this single file.

Parameter Reference

Basic Configuration

Parameter	Value	Description
backend	cmd	Runtime mode. CLI uses cmd
working_dir	.reme	Workspace directory where memory files are stored

metadata — Context Window and Retrieval Parameters

Controls how context space is allocated and how memory is searched:

Parameter	Default	Description
context_window_tokens	100000	Total context window size (tokens)
reserve_tokens	30000	Space reserved for output and system overhead
keep_recent_tokens	10000	How many recent conversation tokens to keep after compaction
vector_weight	0.7	Vector search weight (BM25 = 1 - 0.7 = 0.3)
candidate_multiplier	2	Retrieval candidate pool multiplier. Higher = better recall, slower

Auto-compaction triggers when total message tokens >= context_window_tokens - reserve_tokens, i.e. 70,000 tokens by default.

llms — LLM Models

Parameter	Description
backend	Backend type, uses OpenAI-compatible API
model_name	Model name, defaults to Qwen
request_interval	Request interval (seconds), for rate limiting

embedding_models — Embedding Models

Parameter	Description
backend	Embedding backend type
model_name	Model name, defaults to text-embedding-v4
dimensions	Vector dimensions, 1024

memory_stores — Memory Storage

Parameter	Description
backend	Storage backend, defaults to chroma (ChromaDB)
db_name	Database file name
store_name	Collection name
embedding_model	Which embedding model to use
fts_enabled	Whether to enable BM25 full-text search
vector_enabled	Whether to enable vector semantic search

Recommended to enable both fts_enabled and vector_enabled for the best hybrid retrieval results.

file_watchers — File Monitoring

Parameter	Description
backend	Monitoring mode, full = full scan
memory_store	Corresponding memory store config
watch_paths	Directories/files to monitor
suffix_filters	Which file suffixes to watch (.md)
recursive	Whether to recurse into subdirectories
scan_on_start	Whether to do a full scan on startup

token_counters — Token Counter

Parameter	Description
backend	Counting method, base uses tiktoken

Launch

remecli config=cli

After launch, cli.yaml is loaded automatically and you can start chatting with Remy. ReMe handles compaction and memory in the background.

---

System Commands

Type /-prefixed commands during a conversation to control state:

Command	Description	Blocks
/compact	Manually compact the current conversation; also saves to long-term memory in the background	Yes
/new	Start a new conversation; history is saved to long-term memory in the background	No
/clear	Clear everything, without saving	No
/history	View uncompacted messages in the current conversation	No
/help	Show command list	No
/exit	Exit	No

Comparing the Three Commands

Command	Compaction Summary	Long-Term Memory	Message History
/compact	Generates new summary	Saved	Keeps recent messages
/new	Cleared	Saved	Cleared
/clear	Cleared	Not saved	Cleared

/clear is a hard delete — once cleared, it's gone and not saved anywhere.

---

ReMeCli Capabilities

When Does Memory Get Written?

Scenario	Written To	Trigger
Auto-compaction when context is too long	memory/YYYY-MM-DD.md	Automatic in background
User runs /compact	memory/YYYY-MM-DD.md	Manual compaction + background save
User runs /new	memory/YYYY-MM-DD.md	New conversation + background save
User says "remember this"	MEMORY.md or daily log	Agent writes via write tool
Agent identifies an important decision/preference	MEMORY.md	Agent writes proactively

Memory Retrieval

Two ways to find previously stored information:

Method	Tool	When to Use	Example
Semantic search	memory_search	Don't know where it's stored, fuzzy lookup	"previous discussion about deployment"
Direct read	read	Know the date or file	Read memory/2025-02-13.md

Search uses vector + BM25 hybrid retrieval (vector weight 0.7, BM25 weight 0.3), so both natural language queries and exact keywords work.

Built-in Tools

Tool	Function	Details
memory_search	Search memory	Hybrid vector + BM25 search across MEMORY.md and memory/*.md
bash	Run commands	Execute bash commands with timeout and output truncation
ls	List directory	Show directory structure
read	Read files	Supports text and images, with partial reads
edit	Edit files	Exact text match and replace
write	Write files	Create or overwrite, auto-creates directories
execute_code	Run Python	Execute code snippets
web_search	Web search	Search via Tavily or DashScope

---

How Context Compaction Works

In short, long conversations are condensed into summaries while recent messages stay intact. Two trigger modes:

Auto-Compaction

Before each conversation turn, ReMe checks current token usage. If it exceeds the threshold ( context_window_tokens - reserve_tokens), old messages are automatically compacted:

Before compaction:                    After compaction:
+--------------------------+          +--------------------------+
| Message 1: Hello         |          | Summary: Previously      |
| Message 2: Write code    |  ──────> |   helped user write code |
| Message 3: Tool output   |          |   and make adjustments   |
|   (very long)            |          +--------------------------+
| Message 4: Make changes  |          | Message 5: New request   |
| Message 5: New request   |          +--------------------------+
+--------------------------+

Manual Compaction

Type /compact at any time to force-compact all current messages, regardless of the threshold.

What Gets Preserved in the Summary?

Content	Description	Example
Goal	What the user wants to do	"Build a login system"
Constraints and preferences	Requirements the user specified	"Use TypeScript, no frameworks"
Progress	What's been done so far	"Login endpoint is done, registration still in progress"
Key decisions	What was decided and why	"Chose JWT over sessions for statelessness"
Next steps	What to do next	"Implement password reset"
Key context	File names, function names, errors	"Main file is src/auth.ts"