Memory System

This chapter covers how Ameba-Claw remembers things. “Memory & Personality” explains, from a user’s perspective, what kinds of memory the device keeps and how to view, edit, and clear it; “Memory Internals” goes deeper from a developer’s perspective — covering the two timescales of session history and structured long-term memory, token-budget-based history compression, summary/tag-based retrieval, and automatic extraction after each conversation turn.

Memory & Personality

Ameba-Claw stores the agent’s identity, memory, and session history entirely on the local Flash (VFS). No cloud account is needed, and all data stays on the device. This page describes the three layers of the memory system and how to view, edit, and clear them through the Web console or AT commands.

Note

All memory files are saved to the chip’s local Flash and are never uploaded to any cloud server. Switching LLM providers has no effect on stored memory data.

Memory System Overview

Ameba-Claw organizes memory into three layers, each with a distinct responsibility:

Layer 1 — Identity & Personality

Four Markdown files define who the agent is:

• vfs:/AGENTS.md — The agent’s scope of responsibility and tool-calling strategy (core of the system prompt)

• vfs:/SOUL.md — Personality and communication style, e.g. whether replies are concise, whether the agent proactively offers suggestions

• vfs:/IDENTITY.md — Self-concept: the agent’s name and self-description

• vfs:/USER.md — User profile: name, language preference, professional background, etc.

Layer 2 — Long-term Memory

vfs:/MEMORY.md together with the structured memory database stores facts the agent remembers across sessions, such as user preferences and important past events. After each conversation the agent automatically extracts noteworthy information and writes it into this layer.

Layer 3 — Session History

Each conversation session is stored as a separate .jsonl file under vfs:/session/. The agent can reference past sessions in later conversations, maintaining continuous context.

Comparison of the Three Memory Layers

Layer	Content	How It Changes	Scope of Effect
Identity & Personality	Who the agent is and how it speaks	Edit files manually	All future conversations
Long-term Memory	Remembered facts about the user	Extracted automatically / managed manually	All future conversations
Session History	Current and past conversation turns	Written automatically / cleared manually	Current session and any referenced history

Personality Files

The four files listed below determine the agent’s personality and behavior. You can edit them at any time; changes take effect on the very next message — no restart is required.

Personality File Reference

File	Purpose	Example Content
vfs:/AGENTS.md	Core identity: scope of responsibility and tool-calling strategy	“You are an embedded-hardware assistant focused on Ameba SoC. When a hardware question arises, call the board_hardware_info skill first to look up pin information…”
vfs:/SOUL.md	Personality and communication style: tone, values, behavioral tendencies	“Be concise and direct; avoid unnecessary pleasantries. Proactively suggest checking pin-mux tables when hardware issues come up. Admit uncertainty rather than guessing…”
vfs:/IDENTITY.md	Self-concept: name and self-description	“Your name is Claw. You are an embedded AI assistant running on RTL8721F, powered by the Realtek Ameba-Claw framework…”
vfs:/USER.md	User profile: name, preferences, language	“The user is named Alex, prefers replies in English, is an IoT developer, and primarily uses the RTL8721F development board…”

How to Edit

1. Open the Web console (navigate to the device’s WebIM address in a browser).

2. Go to the Memory page.

3. Locate the file you want, click it to open the editor, and modify the text.

4. Click Save.

Changes take effect immediately. The updated settings will be used starting from the next message you send.

Tip

AGENTS.md and SOUL.md have the most noticeable impact on agent behavior. Start with these two files when tuning how the agent acts and communicates.

Example: Rename the Agent

The following walkthrough shows how to change the agent’s name from “Ameba-Claw” to “Claw”.

Step 1: Open Memory Management

Open the Web console in your browser and click Memory in the left navigation or top menu.

Step 2: Open IDENTITY.md

Find IDENTITY.md in the file list and click it to open the editor. You should see content similar to:

Your name is Ameba-Claw. You are an embedded AI assistant running on Ameba SoC.

Step 3: Change the Name

Replace Ameba-Claw with Claw:

Your name is Claw. You are an embedded AI assistant running on Ameba SoC.

Step 4: Save

Click the Save button on the page. Wait for the success notification to appear.

Step 5: Verify

Send a message in the chat, for example:

What is your name?

The agent should reply with something like “My name is Claw.” If the change does not appear immediately, try refreshing the page and sending the message again.

Note

Renaming the agent only affects how it refers to itself in conversation. It does not change the bot username displayed on IM platforms such as Telegram. The IM username must be updated separately in the respective platform’s bot settings.

Long-term Memory

During conversation, the agent automatically extracts noteworthy facts and saves them to vfs:/MEMORY.md and the structured memory database. As a result, even when a brand-new session begins, the agent retains your preferences and important details from past exchanges.

Examples of what long-term memory stores:

• The user’s name and language preference

• The development board model currently in use

• Recurring requirements or preferences the user has mentioned

• Important historical events (e.g. “the firmware version that flashed successfully last time”)

Managing Memory Through the Web Console

1. Open the Web console and go to the Memory page.

2. Switch to the Long-term Memory tab to see all memory entries displayed as a table.

3. Click the Edit button next to any entry to modify its content.

4. Click Delete to remove a single entry.

5. Click Refresh after making changes to confirm they have taken effect.

Managing Memory Through AT Commands

If you are connected to the device over serial, use the following AT commands:

AT+CLAW=memory,list

Lists all long-term memory entries as a plain-text list.

AT+CLAW=memory,clear

Clears all long-term memory. This action cannot be undone — use it with care.

Warning

AT+CLAW=memory,clear permanently deletes all long-term memory, including the contents of MEMORY.md and every entry in the structured database. If you only want to remove a specific entry, use the Web console to delete it individually.

Session History

Every conversation session is saved as a .jsonl file in the vfs:/session/ directory. The filename typically contains a session ID or timestamp, for example vfs:/session/20240601_143022.jsonl.

When processing a new message, the agent includes the current and relevant past sessions as part of its context, enabling continuous multi-turn conversations.

Managing Sessions Through AT Commands

AT+CLAW=session,list

Lists all session files under vfs:/session/ along with basic information such as filename and size.

AT+CLAW=session,clear

Clears the history of the currently active session. Subsequent messages start in a fresh context, but other saved session files are left untouched.

AT+CLAW=session,clear,all

Clears all session history files, giving the agent a completely clean slate for future conversations.

Tip

If you want the agent to “forget” everything that was said before, run AT+CLAW=session,clear,all. This command does not affect long-term memory (MEMORY.md); that must be cleared separately.

Note

Session history files consume Flash storage. If the device is running low on space, clear old sessions periodically.

Updating Memory Through Conversation

In addition to editing files manually, you can tell the agent directly in the chat what it should remember or forget. The agent translates these instructions into updates to the memory files automatically.

Asking the Agent to Remember Something

Say it directly in the conversation:

Please remember that my name is Alex and I prefer short replies.

The agent updates vfs:/USER.md and long-term memory accordingly and confirms the change. All future conversations will apply this setting.

Asking the Agent to Forget Something

Please forget everything you know about my job.

The agent removes work-related memory entries from USER.md, MEMORY.md, and the structured database, then confirms the deletion.

Updating Communication Style

From now on, please reply to me in English.

The agent saves the language preference to USER.md and switches to English starting with the very next reply.

Tip

Updating memory through conversation is the most natural approach and is ideal for adjusting preferences on the fly. If you need to make larger changes to the agent’s core identity or system prompt, editing AGENTS.md or SOUL.md directly in the Web console gives you more precise control.