Memory
LLMs are stateless—each request starts fresh. ESP-Claw uses claw_memory to inject two kinds of persisted context before each request so the Agent appears to “remember” chats and users.
The two memories target different horizons and solve different problems:
Memory modes
Section titled “Memory modes”ESP-Claw’s memory module provides two modes:
| Mode | Behavior | Best for |
|---|---|---|
Structured memory management (full mode) |
Uses structured records + a summary-tag catalog; recalls details via memory_recall when needed |
Default mode, suitable for continuous use and auto-extraction |
Lightweight memory (lightweight mode) |
Keeps profile and session history; long-term memory mainly injects MEMORY.md text |
Resource-constrained setups or simpler pipelines |
edge_agent uses full mode by default. You can switch in menuconfig at (Top) → App Claw Config → App Claw memory management mode.
Session history: coherence within a conversation
Section titled “Session history: coherence within a conversation”Session history keeps turn-to-turn coherence within one conversation. Without it, every line is a fresh start for the model and prior content cannot be referenced.
ESP-Claw scopes history by Session ID. Turns under the same Session ID form one thread; changing Session ID switches to another isolated thread—ideal for parallel chats from different IM users or channels.
History is capped (max messages and max characters per message). Older turns drop first by design: prevent unbounded token growth and steer durable facts into long-term memory.
Long-term memory: durable knowledge across sessions
Section titled “Long-term memory: durable knowledge across sessions”Long-term memory is shared across all Sessions for facts that outlive one chat: preferences, device summaries, cross-task agreements, and more.
Memory capabilities
Section titled “Memory capabilities”Structured long-term memory supports the following basic operations:
| Operation | Purpose |
|---|---|
memory_store |
Write one long-term memory entry |
memory_recall |
Recall related memories by summary label |
memory_list |
List currently stored memories |
memory_update |
Update an existing memory |
memory_forget |
Delete a specified memory |
Editable profile and soul memory
Section titled “Editable profile and soul memory”Besides structured long-term memory, claw_memory also maintains three editable profile files, and injects them as system context:
| File | Purpose | Suggested content |
|---|---|---|
user.md |
Current user profile | Name/call sign, preferred language, common terms, standing agreements |
soul.md |
Agent “soul” and values | Core style, operating principles, priority order |
identity.md |
Agent identity card | Name, role, capability boundaries, strengths |
You can treat these as “stable behavior settings”, while structured entries in memory_records.jsonl are closer to “retrievable factual memories”.
Structured memory entries
Section titled “Structured memory entries”In the current implementation, long-term memory is not a fixed type enum. It is a structured entry model. Each entry mainly contains:
| Field | Purpose | Example |
|---|---|---|
content |
Memory body (normalized durable fact) | “The user prefers replies in Chinese.” |
tags |
Used to build the summary-label catalog (takes up to the first 1-3) | Chinese,reply-style |
keywords |
Used in keyword index to help locate related entries | Chinese,concise |
source |
Source marker (for example manual, auto_llm) |
auto_llm |
Lightweight retrieval: summary labels
Section titled “Lightweight retrieval: summary labels”ESP-Claw does not rely on a vector database. It uses summary labels for lightweight retrieval. Each memory usually has 1-3 tags, and the system builds a summary-label catalog from them. In full mode, the catalog is auto-injected on each request so the LLM can pick labels first, then call memory_recall for details.
Auto-extraction and deduplication
Section titled “Auto-extraction and deduplication”In full mode, the system attempts auto-extraction from the latest user message at request start: durable information is written into structured memory, with dedup/replace handling before and after writes to avoid repeated accumulation of the same fact.
Note that current auto-extraction is mainly based on user messages; whether device events are stored depends on whether business logic explicitly calls memory_store.
What to store where
Section titled “What to store where”| Content | Prefer |
|---|---|
| Assistant personality, style, values | soul.md |
| Assistant name, role, capability boundaries | identity.md |
| User long-term preferences and communication agreements | user.md + long-term memory (memory_ops) |
| Name, preferences, language habits | Long-term memory (in full mode, prefer managing through memory_ops) |
| Device state, finished-task summaries | Long-term memory (structured records + summary tags) |
| Ephemeral instructions for this chat | Leave in session history—no extra steps |
| One-off facts that span sessions | Write to long-term memory, clear when the task completes |