Memory and Transcripts

The Memory Problem

Out of the box, AI assistants forget everything when the conversation ends. OpenClaw solves this with multiple memory layers — but the one that matters most is the one you write yourself: custom instructions.

This lesson walks you through the two things you actually need to do (write custom instructions, create knowledge files) and then explains how OpenClaw's automatic memory features work under the hood.

Step 1: Write Your Custom Instructions

Custom instructions are a system-level prompt injected into every conversation. This is how you tell your OpenClaw who you are, how you like responses, and what it should always know about you.

SSH into your server and open the file:

ssh claw@YOUR_SERVER_IP
nano ~/openclaw/config/custom-instructions.md

Here's a realistic example you can adapt:

You are my personal AI assistant. Here's what you should know about me:

- My name is Alex. I live in Austin, Texas.
- I work as a freelance graphic designer. I'm interested in typography,
  open-source tools, and small business automation.
- I prefer concise answers. If I need more detail, I'll ask.
- When I ask about code, I primarily use Python and bash scripts.
- My timezone is US Central (CT).
- I use Bitwarden for passwords, Proton Mail for email, and Vultr for hosting.
- I have two cats named Pixel and Vector. Yes, you should ask about them
  occasionally.

Save the file (Ctrl+O, Enter, Ctrl+X). The instructions take effect on your next conversation.

Tips for Good Custom Instructions

• Be specific. "I prefer concise answers" is better than "be helpful."
• Include your tools and stack. This saves you from re-explaining your setup every conversation.
• Keep it under ~500 words. Custom instructions are included in every request and cost tokens. Don't write an autobiography.
• No sensitive information. Don't put passwords, API keys, or financial details here.

Step 2: Create Knowledge Files

Knowledge files are documents that persist across conversations. Put reference material here that you'd otherwise have to paste into chat repeatedly.

Create the knowledge directory:

mkdir -p ~/openclaw/data/knowledge

Add files in any of these formats:

• .md — Markdown (recommended for most notes)
• .txt — Plain text
• .pdf — PDF documents

For example, save a personal notes file:

nano ~/openclaw/data/knowledge/my-notes.md

Write something useful — project notes, a short bio, decisions you've made, preferences you don't want to repeat:

# Project Notes

## Current Projects
- Redesigning portfolio site (deadline: end of month)
- Learning Docker for self-hosting

## Preferences
- I prefer dark themes in all tools
- I use metric units
- My budget for cloud services is $30/month max

Then configure OpenClaw to reference this directory. In your config file:

knowledge:
  path: /app/data/knowledge

Good candidates for knowledge files:

• Your resume or bio
• Project notes you reference frequently
• Personal preferences and decisions
• Reference material for your work

How OpenClaw's Automatic Memory Works

Beyond the files you write yourself, OpenClaw has two automatic memory features that work without any configuration.

Session Memory (Short-term)

Each conversation thread maintains context automatically. When you send a message, OpenClaw includes recent conversation history so Claude understands the context. This works out of the box — nothing to configure.

Lossless Transcript Pruning

This is OpenClaw's key feature for long conversations. It keeps a complete, unmodified record of every conversation on disk while intelligently pruning what gets sent to Claude in each request:

• Your messages and Claude's replies are never modified — the full conversation history is preserved on disk
• Tool results (the bulky parts) get trimmed from older messages to stay within context limits
• For Anthropic models, cache-TTL mode is enabled by default for efficient context reuse

Making Memory Work Well

Do:

• Write clear, specific custom instructions
• Tell your OpenClaw to "remember this" for important facts — some setups can write to knowledge files
• Review your transcript history periodically to understand what context your OpenClaw retains

Don't:

• Assume your OpenClaw remembers everything from last week's conversation
• Put sensitive information (passwords, financial details) in knowledge files
• Make custom instructions too long — they're included in every request and cost tokens

When You're Done

• Custom instructions written and saved
• Knowledge directory created
• At least one knowledge file added (e.g., your notes or bio)
• Lossless transcript pruning understood (it's on by default)
• Tested that your OpenClaw remembers context within a conversation