Project Context and Memory

One of the most common frustrations with AI coding tools is that they forget. You spend an hour explaining your codebase, the decisions you made, the trade-offs you chose, and then the next session starts blank. You are back to square one.

OpenClaw solves this with a layered memory system. The agent does not start fresh every time. It reads your workspace, your memory files, and your session history to build context before it does anything else.

TL;DR: OpenClaw uses MEMORY.md for long-term curated memory, daily logs for raw session data, and workspace files for project context. This layered approach means the agent remembers your projects, decisions, and preferences across sessions.

The Memory Layer Stack

OpenClaw loads memory in a specific order at the start of every session.

First, SOUL.md and USER.md are read. These define the agent personality and your personal context. This is lightweight and stable.

Then, daily memory logs from today and yesterday are read. These live in memory/YYYY-MM-DD.md and capture what happened in recent sessions. They are raw and unfiltered.

Finally, in main session direct chats, MEMORY.md is loaded. This is the curated long-term memory, where significant decisions, project state, and learned preferences are distilled and kept.

Daily logs are the raw material. MEMORY.md is the final output after review. Think of daily logs as your journal and MEMORY.md as the Wikipedia article about you.

How Context Carries Over

When you work on a project, the agent can write session notes to the daily log. It might note what files you modified, what decisions were made, what the next steps are. The next session, when it reads that log, it picks up where you left off.

This only works if the agent writes those notes. You can also write them yourself. The convention is that if something matters, write it down in the daily log or MEMORY.md.

Context carries over through files, not through conversation history. If you made a decision in session, document it in the memory files. The agent does not carry implicit context between sessions, only explicit file-based context.

When to Update Memory

The agent updates daily logs automatically during sessions, but it is not perfect. You should actively update memory when something significant changes.

Update MEMORY.md when you make architectural decisions, change your tech stack, establish conventions, or learn something about your workflow that you want to preserve. This is curated memory, so it should be clean and organized, not a dump of everything.

Update daily logs when you finish a working session. Note what you did, what is pending, what to check next. Even a few bullet points help the next session start faster.

If you find yourself re-explaining the same thing across sessions, that is a signal to write it down somewhere permanent. MEMORY.md or a project-specific file in the workspace is the right place.

Workspace Files as Context

Beyond the dedicated memory files, your workspace itself is a source of context. The agent reads AGENTS.md, SOUL.md, USER.md, and TOOLS.md on startup. These files live in the workspace and are always available.

If you want the agent to know something about your environment, your tools, your devices, or your conventions, put it in these files. TOOLS.md in particular is where you store local specifics like SSH aliases, camera names, or TTS preferences. Skills reference TOOLS.md for environment-specific data.

Project-specific context should live in project directories. OpenClaw can read files anywhere in the workspace, so if you have a README with project conventions, architecture notes, or setup instructions, keep those in the project folder.

Memory in Group Chats vs Direct Chats

MEMORY.md is only loaded in main session direct chats. It is not loaded in group contexts, shared channels, or any session where other people are present. This is intentional and important for privacy.

What this means in practice: if you are working in a group chat, the agent has session context but not your long-term personal memory. It will not know your preferences, your personal projects, or anything else that lives in MEMORY.md. This is the right behavior. You do not want your personal context leaking into group conversations.

If you need the agent to know something in a group context, mention it in your message. The agent will pick it up from the conversation, but it will not pull from MEMORY.md automatically.

Practical Pattern for Keeping Context

The practical workflow for good context continuity looks like this.

During a session, let the daily log capture what is happening. At the end of the session, if significant decisions were made, update MEMORY.md with the distilled version.

Before a new session, the agent reads the daily logs and MEMORY.md automatically. You do not need to re-explain things that are documented.

When starting work on a new aspect of a project, create or update a project-specific file that captures the current state. This could be a TODO, a README section, or just a note in the daily log.

The goal is that by the third or fourth session on a project, the agent knows the stack, the conventions, the current state, and what you are working toward. You spend less time on setup and more time on actual work.

Sources: OpenClaw AGENTS.md