🧠 Teaching Your AI to Remember

How memory works, what files to create, and copy-paste prompts to train your AI without burning tokens.

The Problem: Your AI Has Amnesia

Every conversation, your AI wakes up completely fresh.

It has no idea who you are, what you do, or what you worked on yesterday.
Without a memory system, you'll spend the first 10 minutes of every conversation re-explaining your business — burning tokens and your patience.

OpenClaw solves this with a workspace folder — a set of files your AI reads automatically at the start of every conversation. Think of it as a briefing packet your AI gets before every meeting.

⚠️ The catch: That briefing packet has a size limit — about 25,000 characters. If your files get too big, the AI starts reading them in half, silently missing context. The goal is to keep your files lean and organized so the AI always gets the full picture.

The 3-Tier Memory System

Not everything needs to be read every session. Organize your memory into three tiers:

🔴 Tier 1 — Always Loaded

Bootstrap Files

Read automatically every single session. Keep these lean.

  • USER.md — who you are
  • SOUL.md — AI personality
  • TOOLS.md — live systems
  • MEMORY.md — key decisions
Target: under 70% of budget
🟡 Tier 2 — On-Demand Index

Fast Lookup

Checked when needed. Small and current.

  • knowledge-index.json
  • CONTINUATION.md
  • STATUS.md
What's broken, in progress, hot facts
🔵 Tier 3 — Deep Archive

Searchable History

Only pulled when specifically needed.

  • memory/YYYY-MM-DD.md
  • memory/projects.md
  • memory/people.md
  • memory/learnings.md
Raw logs, history, decisions

What Goes Where

If it's...Put it in...Why
Your name, role, how to reach youUSER.mdNeeded every session
Your business descriptionUSER.mdCore context
How you want the AI to behaveSOUL.mdPersonality, tone, rules
Live server IPs, deploy commandsTOOLS.mdActive infra only
A decision you made and whyMEMORY.mdDistilled, not raw
What's broken or in progress RIGHT NOWknowledge-index.jsonChanges frequently
Raw notes from today's sessionmemory/YYYY-MM-DD.mdAppend-only log
Completed project historymemory/projects.mdArchive, searchable
Team member bios, vendor detailsmemory/people.mdOnly needed sometimes
Hard lessons learnedmemory/learnings.mdPromoted from logs

Do's and Don'ts

✓ Do This

  • Keep USER.md under 5,000 characters
  • Write daily notes to memory/YYYY-MM-DD.md
  • Promote decisions to MEMORY.md
  • Use knowledge-index.json for hot facts
  • Write CONTINUATION.md before long sessions end
  • Ask your AI to "check memory for [topic]"
  • Trim stale content every few weeks

× Don't Do This

  • Don't put everything in USER.md
  • Don't re-explain your business every session
  • Don't let TOOLS.md grow indefinitely
  • Don't load old session logs as bootstrap files
  • Don't leave the AI to guess your preferences
  • Don't start projects without checking memory first
  • Don't forget to write things down — mental notes die on restart

Copy-Paste Setup Prompts

Use these prompts to build your memory files from scratch. Paste them into your AI chat and answer the questions — your AI will create the files for you.

📝 Prompt 1 — Create Your USER.md

Start here

This creates the core file your AI reads every session — who you are, your business, and how you like to work.

I need you to create my USER.md file — the core memory file you'll read at the start of every conversation. Ask me the following questions one at a time, then compile my answers into a well-structured USER.md file: 1. What's your full name and what should I call you? 2. What's your business? (name, what you do, who you serve) 3. What's your timezone and primary phone number? 4. Who are the key people on your team? 5. What platforms and tools do you use daily? 6. How do you like to communicate? (short bullets? detailed? formal?) 7. What frustrates you most when working with an AI assistant? 8. What does "done" mean to you — what's your definition of a completed task? After I answer all 8 questions, create the USER.md file in my workspace at ~/.openclaw/workspace/USER.md

🎭 Prompt 2 — Define Your AI's Personality

SOUL.md

This shapes how your AI talks to you — tone, style, and behavior rules.

I need you to create my SOUL.md file — this defines your personality and how you should behave with me. Here's what I want you to ask me: 1. What should I call you? (give your AI a name and emoji) 2. What tone do you prefer — formal, casual, direct, warm? 3. Should I give you opinions and recommendations, or just options? 4. What should I always do before taking action on your systems? 5. How should I handle it when I'm blocked or uncertain? 6. What's one thing you never want me to do? After I answer, create ~/.openclaw/workspace/SOUL.md with clear rules I'll follow every session. Make it personal — not corporate.

🔧 Prompt 3 — Document Your Tech Stack

TOOLS.md

Tells your AI about your live systems so it never asks "what server are you on?" again.

I need you to create my TOOLS.md file — a reference sheet for all my live systems and tools. Ask me: 1. What computer are you running OpenClaw on? (Mac, Windows, Linux?) 2. Do you have a cloud server (VPS)? If yes, what's the IP and how do you connect? 3. What services or websites are you running? (list each with its URL and where the code lives) 4. What APIs do you use? (just the names — we'll store keys separately in .secrets) 5. Are there any deploy rules I must never break? (e.g. "never edit dist/ files directly") 6. Any known fragile points in your setup I should be careful around? After I answer, create ~/.openclaw/workspace/TOOLS.md — keep it under 4,000 characters. Active infrastructure only, no history.

💡 Prompt 4 — Seed Your Memory with Key Decisions

MEMORY.md

Gets important decisions and hard-won lessons into long-term memory right away.

I need to seed my MEMORY.md with the most important context from my business. Ask me these questions: 1. What's the most important thing I should always know about your business situation right now? 2. What's a decision you made recently that I should never reverse without asking you? 3. Is there anything you've learned the hard way that I should never repeat? 4. What's currently broken or in progress that I should be aware of? 5. Who are the most important people I'll be helping you deal with? After I answer, create ~/.openclaw/workspace/MEMORY.md with a clean "Snapshot" section and a "Decision Log" table. Keep it under 100 lines — distilled insights only, not raw notes.

📊 Prompt 5 — Health Check Your Memory

Run monthly

Run this once a month to keep your memory files lean and accurate.

Run a memory health check on my workspace. Do the following: 1. Read USER.md, TOOLS.md, SOUL.md, MEMORY.md and AGENTS.md 2. Report the character count of each file and what % of the 5,000-char per-file limit each is at 3. Report the total bootstrap budget usage (out of 25,000 chars) 4. Flag anything that looks outdated, stale, or redundant 5. Suggest what could be trimmed or moved to the archive (memory/ subfolder) 6. Do NOT make any changes yet — just show me the report and proposed cuts, then wait for my approval Format it as a clean table so I can see it at a glance.

Saving Tokens Without Losing Context

Start sessions with context

Begin every conversation with: "Check memory for [topic]" before asking your question. This triggers a targeted search instead of re-explaining everything.

✂️

Keep files trim

Every character in your bootstrap files costs tokens on every session. A 1,000-char bloated section = wasted tokens every single day.

📦

Archive, don't delete

Move old content to memory/projects.md or memory/people.md instead of deleting. Your AI can still find it via search — it just won't load it every session.

🔖

Write handoff notes

Before ending a long session, ask your AI: "Write a CONTINUATION.md with our current state." Next session it picks up exactly where you left off.

🗂️

Use the knowledge index

knowledge-index.json is your AI's fast-access cheat sheet — small, always current, loaded every session. Put "what's broken right now" there, not in MEMORY.md.

🚫

Don't bootstrap heartbeat files

Files like HEARTBEAT.md or setup guides shouldn't be in your root workspace folder — they load every session for no reason. Move them to a system/ subfolder.

The Golden Rule

If it wasn't written down, it didn't happen.
Your AI wakes up fresh every session. Every decision, every preference, every hard-won lesson — if it's not in a file, it's gone.