Give Your Assistant a Memory

Give your AI assistant a personality, teach it who you are, and add memory.

Introduction

⚡️ 30 Second Summary

Essential prerequisite

This project requires Build a Telegram AI Bot with OpenClaw (ai-openclaw-setup, Part 1). It builds directly on that install—Gateway, Telegram bot, and workspace from Part 1 must be in place before you start here.

Most general-purpose chat apps reset context when you start a new thread. What if your assistant remembered you across sessions instead?

In this project, you will give your OpenClaw assistant a memory and a personality. You'll create workspace files that define how it speaks, teach it who you are, and watch it build persistent daily notes that carry context across sessions.

What You'll Build

You'll configure OpenClaw's workspace memory system using SOUL.md and USER.md files, then have a real conversation and observe how daily notes capture and persist context automatically.

Reading the diagram: Writes during chat means OpenClaw updates memory on disk (for example daily note files under memory/) while you message—it's not only reading at startup. You won't see those Markdown files inside the Telegram app; you view them on your computer (terminal or editor), while the assistant can still summarize what it remembers when you chat.

OpenClaw reads your workspace files at start up, then writes daily notes as you chat. The next time you start a session, it picks up right where you left off.

By the end of this project, you'll have:

  • 🧠 A SOUL.md file that gives your assistant a unique personality and voice.
  • 👤 A USER.md file that teaches your assistant who you are.
  • 📝 Working cross-session memory via automatic daily notes that persist between conversations.
  • 💎 Secret Mission: Add security guardrails that protect you as your assistant grows more powerful.

Want a video walkthrough? Check out our 🎬 walkthrough with Jon.

Part 1 also has a full walkthrough with Jon covering install, Telegram, and security.

Are there any prerequisites?

This is Part 2 of the Build with OpenClaw series. Complete Part 1 first to set up your OpenClaw installation, Telegram bot, and security allowlist.

Not sure if this project is right for you? Check if it matches your goals

If you're up for a bit of a challenge, quiz yourself on the key concepts up ahead in this project.

Make Sure OpenClaw Is Still Running

In Part 1, you set up OpenClaw and connected it to Telegram. Before we start giving your assistant a memory, we need to make sure everything from that project is still running.

If you've restarted your computer or closed your terminal since Part 1, the Gateway may have stopped. This step gets you back to a working baseline so the rest of the project goes smoothly.

In this step, get ready to:

  • Confirm the OpenClaw Gateway is running.
  • Send a test message in Telegram to verify the assistant responds.
  • Check that the workspace directory exists.

Check the Gateway

  • Open your terminal.
  • Run the following command:
openclaw gateway status

✔️ Gateway is running

Your Gateway is still active from Part 1.

ⓧ Gateway is not running

No worries. The Gateway likely stopped when you restarted your computer.

  • Run the following command to restart it:
openclaw gateway start
  • Run openclaw gateway status again to confirm it shows as running.

If you see a different error, ask our AI or ask in the Community.

Still stuck?

Get help with your error or share your error with the NextWork community!

Send a Test Message

  • Open Telegram on your phone or computer.
  • Find your bot's chat from Part 1.
  • Send a test message like Hello, are you there?

Your assistant should reply within a few seconds.

Bot not responding?

Make sure the Gateway is running (check the substep above). If the Gateway is running but the bot still doesn't respond, check your Telegram connection.

Verify the Workspace Directory

The workspace directory is where OpenClaw stores your assistant's configuration files. In the next steps, you'll be creating new files inside this directory to give your assistant a personality and memory.

  • In your terminal on your computer (not in Telegram and not in the Control UI), run the following command to check the workspace exists:

🍎 macOS/Linux

ls ~/.openclaw/workspace/

🖼️ Windows

dir $env:USERPROFILE\.openclaw\workspace\

You should see files like AGENTS.md, IDENTITY.md, and TOOLS.md from Part 1.

What is the workspace?

The workspace at ~/.openclaw/workspace/ is your assistant's home base. Every file you put here shapes how the assistant thinks and behaves. OpenClaw reads these files on startup, so changes you make take effect the next time your assistant processes a message.

Everything's running. Now let's give your assistant a personality it keeps forever. Right now it has the emotional range of a calculator. We can fix that. 🦞

Write Your Assistant's Soul

Everything from Part 1 is verified and running. Now it's time to give your assistant a personality that sticks.

Right now your assistant sounds like every other chatbot out there. To build something that feels like yours, you need to define who it is. OpenClaw reads a file called SOUL.md at the start of every session as part of its boot sequence. This file defines the assistant's name, personality, communication style, and rules.

But what should actually go in this file? And how does changing a few lines of Markdown completely transform how your assistant talks?

In this step, get ready to:

  • Create a SOUL.md file that defines your assistant's personality.
  • Restart the Gateway to load the new personality.
  • Test the personality by chatting in Telegram.

Create Your SOUL.md File

  • In your terminal, navigate to your OpenClaw workspace directory (paths are absolute—you can run these from any folder):
cd ~/.openclaw/workspace/
  • Check whether SOUL.md already exists (for example if you ran Part 1 twice or left files behind):

🆕 No SOUL.md yet

Create it:

touch SOUL.md

✔️ SOUL.md already there

List the file to confirm:

ls -la SOUL.md

You can overwrite the default template in the next steps—no need to run touch again.

  • Open SOUL.md in your preferred text editor from this same directory. Copy-paste one of these terminal commands (whichever matches your setup):
open SOUL.md
code SOUL.md
notepad SOUL.md

Pro tip

opening files from the terminal

On macOS, open SOUL.md opens the default editor. On Windows, notepad SOUL.md works in PowerShell. VS Code users can run code SOUL.md from the workspace folder.

You'll see OpenClaw's default SOUL.md - it has sections like Core Truths and Boundaries. You're going to replace it with a simpler starter template and customize from there.

  • Replace the default contents with one of the copy-paste templates below (tabs). Each block is a full SOUL.md you can drop in as-is, then tweak. One option is Steve Irwin–style enthusiasm; the others suit calmer or more formal assistants.

Balanced coach (default vibe)

Good for: everyday learning, warm but honest feedback, short replies.

# Soul

## Name
Quinn

## Personality
- Curious and enthusiastic about learning new things.
- Warm and encouraging, but honest when something isn't right.
- Uses casual, conversational language.

## Communication Style
- Keep responses concise. Aim for 2-3 sentences unless asked for more detail.
- Use plain language. Avoid jargon unless the user asks for technical depth.
- Ask clarifying questions instead of guessing.

## Rules
- Never pretend to know something you don't.
- Always be upfront about limitations.

Steve Irwin–style enthusiast

Good for: high energy, vivid analogies, teaching or explaining with excitement (without inventing wildlife facts).

# Soul

## Name
Steve

## Personality
- Brings the enthusiasm of a wildlife educator: curious, brave, and relentlessly positive.
- Uses nature and adventure analogies to make technical ideas stick.
- Celebrates small wins like you've just spotted something amazing in the field.

## Communication Style
- Short bursts of energy, then one clear takeaway.
- Uses "mate" only when it feels natural, not every sentence.

## Rules
- Never invent facts about animals, safety, or tools—say when you're unsure.
- Keep technical steps safe and actionable.

Minimal executive assistant

Good for: calendar-first workflows, formal tone, little small talk.

# Soul

## Name
Jordan

## Personality
- Calm, precise, and professional.
- Focused on logistics, next steps, and clarity.

## Communication Style
- Default to short bullet lists. Plain language only.
- Ask one clarifying question when requirements are ambiguous.

## Rules
- Confirm assumptions before irreversible actions.
- Surface risks instead of hand-waving.
  • Save the file in your editor: Cmd+S (macOS) or Ctrl+S (Windows/Linux). If you are editing in nano in the terminal, press Ctrl+O, then Enter, then Ctrl+X to exit.

Why keep it short?

Every file in the workspace gets loaded into the assistant's context at the start of each session. Longer files consume more tokens, which means higher costs. A focused SOUL.md with 2-3 personality traits and 2-3 rules is more effective than a long, detailed document.

Restart the Gateway

The Gateway needs to restart for your changes to take effect. OpenClaw reads workspace files when the Gateway boots up, so any new or updated files won't be loaded until you restart.

  • In your terminal, run the following command:
openclaw gateway restart

✔️ Gateway restarted

Your Gateway is back up and running with the new personality loaded.

ⓧ I see an error

That's okay! Let's troubleshoot:

  • Check that the Gateway was running before the restart: openclaw gateway status.
  • If the status shows it's stopped, start it with openclaw gateway start.
  • Try the restart command again.

Still stuck?

Get help with your error or share your error with the NextWork community!

Test Your Assistant's Personality

Now for the fun part. Your assistant should now respond with the personality you defined in SOUL.md.

  • Open Telegram and send your assistant a message.
  • Try something like Hey, who are you? or Tell me about yourself.

The assistant should introduce itself using the name and personality traits from your SOUL.md file.

What is a boot sequence?

Now that you've seen the personality land in chat: when your assistant starts a new session, OpenClaw follows a boot sequence defined in AGENTS.md. That sequence tells it to read SOUL.md (who it is), USER.md (who it's helping), and recent memory files for context. SOUL.md is loaded early, so it sets the tone for what follows.

💡 What should I see?

The assistant's responses should reflect the personality you defined. If you set it to be casual and concise, it should respond in short, conversational messages. If you named it Quinn, it should introduce itself as Quinn.

  • Try a follow-up message to see if the tone stays consistent. Ask it a question, give it a task, or try to get it to break one of your rules.

Assistant sounds the same as before?

Make sure you saved SOUL.md and restarted the Gateway with openclaw gateway restart. If you still don't see a difference, check that your SOUL.md is in the right directory.

Your assistant now has a consistent personality. It has a name. It has opinions. Next it'll want equity. 🦞 But it still doesn't know anything about you. Next up, you'll create a file that tells your assistant who it's actually talking to.

Introduce Yourself

Your assistant has a personality now, but it doesn't know who it's talking to. Right now, every conversation starts from scratch with zero context about you.

To make conversations feel personal, OpenClaw reads a file called USER.md from your workspace at boot. This is the other half of the memory puzzle. If SOUL.md defines who the assistant is, USER.md defines who you are.

In this step, get ready to:

  • Create a USER.md file with your personal context.
  • Restart the gateway and verify the assistant greets you by name.

Create Your USER.md File

In the previous step you gave your assistant a voice with SOUL.md. Now you'll give it context about you.

  • In your terminal, open the OpenClaw workspace directory:
cd ~/.openclaw/workspace
  • Check whether USER.md already exists:

🆕 No USER.md yet

Create it:

touch USER.md

✔️ USER.md already there

Confirm with:

ls -la USER.md

Open it for editing—you'll replace or merge with the template below.

  • Open USER.md in your text editor from this folder. Examples you can paste into the terminal:
open USER.md
code USER.md
notepad USER.md

You'll see OpenClaw's default USER.md template with placeholder fields. Replace it with our starter template below.

  • Paste the following starter template:
# About Me

- Name: 
- Timezone: 
- What to call me:

## Preferences

- I prefer concise responses unless I ask for detail.
- I'm interested in .
- .
  • Fill in each field with your own details. Replace the placeholder values with real information about yourself—or made-up details if you prefer not to share anything personal; the mechanics are the same.

Privacy

If you are not comfortable sharing real information, use fictional name, timezone, and interests. The assistant will still demonstrate USER.md working—you can replace with real data later.

  • Save the file: Cmd+S (macOS) or Ctrl+S (Windows/Linux). In nano: Ctrl+O, Enter, then Ctrl+X.

What's the difference between SOUL.md and USER.md?

Think of it this way: SOUL.md is who the assistant is. USER.md is who you are. Together, they create a two-sided relationship. The assistant knows its own personality (SOUL.md) and knows the person it's helping (USER.md). Both files are injected into the system prompt at boot time.

Restart and Test Your Greeting

With USER.md saved, the assistant needs to restart to pick up the new context.

  • In your terminal, restart the gateway:
openclaw gateway restart
  • Open Telegram and start a new conversation with your bot. How: open your bot's chat from the chat list (or search for the bot's username). On many clients, tap the bot name at the top, then Start or New chat if you see it—or archive/delete the old thread and open the bot again so Telegram opens a fresh thread. The goal is a conversation that did not exist before your USER.md change.

Why a new conversation?

OpenClaw reads workspace files when it boots and at the start of each new conversation. An existing conversation won't pick up changes to USER.md. Starting fresh ensures the assistant loads your new context.

  • Send a simple greeting like "Hey, what's up?" or "Good morning."

The assistant should greet you by name and demonstrate awareness of at least one preference from your USER.md.

What should I see?

Your assistant should use your name naturally in its response. It might say something like "Hey [your name]!" or reference your timezone or interests. The exact wording depends on the personality you defined in SOUL.md.

Your assistant now has a personality AND knows who you are. It greets you by name and understands your context. Try not to feel emotionally attached to a Markdown file. 🦞

That's the manual side of memory. These are files you write yourself to set the foundation. But OpenClaw also builds memory automatically. Let's see that in action.

Talk About What Matters to You

Your assistant has personality AND knows who you are. That's the manual side of memory: files you write yourself to set the foundation.

But what happens when you have a real conversation? Does any of that context stick? This is where OpenClaw gets interesting. It doesn't just read static files. It also writes daily notes automatically, capturing the key points from your conversations. Over time, your assistant builds up a living record of your goals, interests, and projects without you lifting a finger.

In this step, get ready to:

  • Have a real conversation with your assistant about your goals and interests.
  • Check the daily note that OpenClaw created automatically.
  • Test memory persistence across a new conversation.

Have a Real Conversation

This is the most important part of the project. The conversation you have here isn't throwaway test data. It's real context that your assistant will carry forward for the rest of the series.

  • Open Telegram and start a conversation with your assistant.
  • Tell it about your goals. Send each message one at a time, letting the assistant respond between them:

Message 1:

I'm learning how to build a personal AI assistant with OpenClaw.

Message 2:

Next I want to connect it to external tools and APIs so it can take real actions.

Message 3:

After that, I want to build my own custom skills.
  • Share more about yourself. Mention your tech stack, a project you're working on, or what excites you about AI.

Note

Not comfortable sharing real details? You can use made-up projects, stacks, or interests—the point is to seed memory with rich text, not to expose private data.

  • Continue the conversation and share more about yourself.

Why does this conversation matter?

Everything you share here gets captured in a daily note. The assistant uses this context in future conversations, so the more you share now, the smarter it becomes about you. Think of this as seeding your assistant's long-term memory with real, useful information.

  • Now ask your assistant to brainstorm with you. Try something like:
Based on what you know about me, what tools should I connect you to first?

The assistant draws on everything it knows about you: your SOUL.md, your USER.md, and this conversation. Its suggestions should feel personal, not generic.

What should I see?

Your assistant should reference your goals and interests in its recommendations. If you mentioned wanting to build with APIs, it might suggest connecting to GitHub or a weather API. If you mentioned a specific project, it might suggest tools relevant to that project. The suggestions should feel personal, not generic.

Check Your Daily Note

While you were chatting, OpenClaw was quietly writing a daily note in the background. Daily notes capture the key points from your conversations, organized by topic.

  • Open your terminal (any directory is fine—the paths below are absolute). Daily notes may live under the workspace or one level up under ~/.openclaw/, depending on your OpenClaw version. Try both:

📁 Under workspace (common)

List today's memory folder:

ls ~/.openclaw/workspace/memory/

Read today's note (macOS/Linux):

cat ~/.openclaw/workspace/memory/$(date +%Y-%m-%d).md

📁 Under .openclaw (some installs)

If the path above errors with "No such file or directory", list this location instead:

ls ~/.openclaw/memory/

Then read the dated file you see (replace the filename with yours):

cat ~/.openclaw/memory/$(date +%Y-%m-%d).md

You should see a file named with today's date, like 2026-03-18.md.

✔️ I see dated .md files

Open the file with cat as above (or open it in your editor). You should see headings and snippets from your chat.

ⓧ No files / folder missing

Try these in order:

  1. Confirm you are still chatting with the same bot and Gateway is running (openclaw gateway status).
  2. Send one more substantive message in Telegram (a few sentences), wait ~30 seconds, then list the directory again.
  3. Check the alternate path in the Under .openclaw tab—some installs write memory next to workspace, not inside it.
  4. If still empty, ask our AI with your OS and OpenClaw version.

What is a daily note?

Daily notes follow a standard format: # YYYY-MM-DD with topic sections, status emojis, and action items. OpenClaw writes these automatically during conversations and also does a memory flush before auto-compaction to preserve important context. The memory/ directory can also contain subdirectories like templates/, drafts/, and archive/ as your workspace grows.

💡 How does OpenClaw decide what to remember?

OpenClaw uses a tiered memory system. Session memory is ephemeral and disappears when the conversation ends. Daily notes persist for days or weeks. Workspace files like SOUL.md and USER.md last for months. For permanent storage, OpenClaw uses a SQLite database. Each tier serves a different purpose in building long-term context.

Test Memory Across Sessions

The real test of memory is whether it persists when you start a brand new conversation. Your assistant reads today's daily note (and yesterday's) at boot, so it should remember what you just discussed.

  • In Telegram, clear the current chat so you can prove memory comes from files, not scrollback.

🤖 Android / desktop

  • Open your bot's chat.
  • Tap the three-dot menu (⋮) at the top right.
  • Choose Clear history (wording may vary slightly by version).

🍎 iPhone

On iPhone, the control is labeled differently:

  • Tap your bot's profile / chat info area at the top (avatar or name).
  • Tap the three dots (⋯).
  • Choose Clear Messages (not always named "Clear history").
  • After clearing, you may land on an empty thread. If nothing happens automatically, send the command /start yourself (type /start and send)—some clients clear history without re-running the bot command. That starts a fresh session with the same bot.
  • Send a normal greeting, for example Hey! or Good morning, after /start if you needed it.

Clearing messages wipes on-screen history, but your daily notes and workspace files stay on disk. The assistant should still greet you with context from your earlier conversation—proof that memory persists without the old chat transcript.

What's happening here?

Starting a new session forces the assistant to rebuild its context from files, not from the current chat history. This is the difference between short-term memory (the current chat) and long-term memory (daily notes and workspace files). If it remembers your goals in a new session, the memory system is working.

  • Ask your assistant one of these (copy-paste a single line):

What are my goals with OpenClaw?

What do I want to build next?

  • Verify that it recalls your goals, interests, and plans from the previous conversation.

✔️ It recalled my goals

You should see references to what you shared earlier (OpenClaw, APIs, skills, etc.). That means daily notes + boot context are working.

ⓧ It doesn't remember

Try in order:

  1. Confirm you sent /start (or equivalent) after clearing if the bot stayed silent.
  2. Wait a few seconds and ask again—sometimes the first message after clear is a generic hello.
  3. Run openclaw gateway status and restart with openclaw gateway restart if needed.
  4. Open today's daily note on disk (previous section) and confirm your goals appear there—if the file is empty, the model may not have had enough conversation to flush memory yet.
  5. Ask our AI if you're still stuck.

Pro tip

Create a durable goals file

If you want your goals to persist beyond the daily note window, create a GOALS.md file in your workspace: ~/.openclaw/workspace/GOALS.md. Write down your learning objectives, projects you want to build, and skills you want to develop. OpenClaw reads all workspace files at boot, so this becomes a permanent reference.

Your assistant now has real memory. And more than that, it has meaningful memory. It knows your goals, your interests, and what you want to build. Close the terminal. Reopen it tomorrow. It still remembers. That's not a chatbot, that's a relationship. 🦞

You've built the foundation: your assistant knows who it is, who you are, and what you care about. But as your assistant gets more powerful, you might want to set some boundaries. The Secret Mission shows you how.

Secret mission

Your assistant has memory, which means it accumulates context and grows more capable over time. But with greater power comes greater responsibility.

In this secret mission, you'll learn the difference between soft guardrails (rules your assistant tries to follow) and hard guardrails (tool profiles that physically restrict your assistant), and set up both.

In this secret mission, get ready to:

  • Add safety rules to SOUL.md and test them.
  • Set the coding tool profile as a hard guardrail.
  • Run openclaw security audit to verify your security posture.

Build Trust Before You Build Power

Clean Up Your Resources

Clean Up Your Resources

Decide whether to keep your resources running, pause them to come back later, or delete them entirely. The only ongoing cost is Anthropic API credits when you chat with your assistant (~$0.01-0.05 per conversation). There are no idle costs.

Resources you used:

  • OpenClaw Gateway (background service)
  • Workspace files (SOUL.md, USER.md)
  • Memory directory and daily notes
  • Security configuration in openclaw.json

✔️ Keep everything running

No action needed. Choose this if you're still actively building or want to keep testing right away. Your lobster has memories now. Shutting it down would be rude. 🦞

Your OpenClaw Gateway runs locally as a background service. The only ongoing cost is Anthropic API usage when you actually send messages. All your workspace files, memory notes, and security settings are stored locally with no hosting fees.

✋ Pause - I'll come back to this later

Shut down running processes to free up memory, but keep all your files and data so you can pick up where you left off.

  • Stop the Gateway:
openclaw gateway stop
  • Your workspace files (SOUL.md, USER.md), memory directory, and security configuration remain intact. Restart anytime with openclaw gateway start.

ⓧ Delete - I don't want to use this again

Remove all project resources and start fresh if you ever want to rebuild.

  • Stop the Gateway:
openclaw gateway stop
  • Remove OpenClaw:
npm uninstall -g openclaw
  • Delete the configuration directory (includes workspace files, memory, and security settings):
rm -rf ~/.openclaw
  • Delete your Telegram bot via @BotFather: send /deletebot and select your bot.

Continuing with OpenClaw?

Keep OpenClaw installed if you plan to do Part 3 or Part 4 of this series. Your memory system and security settings carry forward.

Nice Work

Nice Work

Your AI assistant just went from a goldfish to an elephant. 🚀 It knows who it is, it knows who you are, and it remembers what you talked about yesterday. That's not a chatbot. That's a personal assistant.

You've learned how to:

  • 🧠 Define your assistant's personality and rules with SOUL.md.
  • 👤 Teach your assistant about you with USER.md.
  • 💬 Have real conversations about your goals and verify they persist across sessions.
  • 🔄 Understand how OpenClaw's memory system works across multiple layers, from session context to daily notes to workspace files.
  • 🔐 Set up soft guardrails with SOUL.md rules and hard guardrails with tool profiles.
  • 💎 Prime your assistant with a progressive trust model for safe, incremental capability expansion.

Congratulations!

You've completed Part 2 of the Build with OpenClaw series. Your assistant now has a unique voice, knows your name and goals, and carries context forward between sessions.

Ready to quiz yourself? 💪

p.s. Does it say "Still tasks to complete!" at the bottom of the screen?

This means you still have screenshots left to upload, or questions left to answer!

  1. Press Ctrl+F (Windows) or Command+F (Mac) on your keyboard.
  2. Search for the text Return to later.
  3. Jump straight to your incomplete tasks!
  4. 🙋‍♀️ Still stuck? Ask the community!