Instructions vs. Memory

Agents in Pinchy have two places to hold knowledge: Instructions and Memory. They look similar — both are Markdown, both shape future replies — but they serve different jobs. Putting knowledge in the wrong place is the most common reason agents feel forgetful, repetitive, or "drift" over time.

This page is the short version. Use it as a cheat sheet when you're editing an agent.

The two stores

Instructions — what the agent is and how it operates. Loaded at the start of every conversation. In Pinchy, this is the SOUL.md (Personality tab) plus AGENTS.md (Instructions tab).
Memory — what the agent has learned across conversations. Stored in MEMORY.md and daily logs under memory/YYYY-MM-DD.md. Written automatically when the agent decides something is worth keeping, or explicitly when you tell it to "remember this."

A useful mental model: Instructions are the job description you hand a new hire on day one. Memory is the notebook they fill in as they work.

The heuristic

| Question | Where to put it | | ------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | WHO is the agent? (persona, tone, language) | Instructions — SOUL.md | | HOW does the agent behave? (rules, SOPs, tool order) | Instructions — AGENTS.md | | Stable fact, relevant every session (product list, tax rates, IDs) | Memory — say "remember this" in chat | | User preference learned from interaction | Memory — auto-memory usually catches this on its own | | One-off detail for a single conversation | Don't persist — leave it in chat context | | Large body of knowledge (manuals, policies, codebases) | Knowledge base — mount as a data directory and use a knowledge-base agent |

If you're still not sure: ask yourself whether a brand-new conversation tomorrow would need this. If yes, persist it. If only this conversation needs it, don't.

Why the distinction matters

Memory and Instructions have different lifetimes and load rules:

Memory survives compaction. When a conversation gets long, the agent runtime compacts the chat history into a summary — older messages disappear. Memory entries already written to MEMORY.md or memory/ do not. Anything important enough to outlive a single thread belongs in Memory, not in the chat itself.
Memory is written as the agent learns — not salvaged at the last second. Pinchy's agents persist memory the moment they decide something is worth keeping (auto-memory), or when you say "remember this" — through a governed write tool that keeps every save auditable. There is no separate last-moment flush right before compaction, so don't rely on one: if a detail matters beyond this thread, make sure the agent has actually saved it.
You can compact on demand. If a long conversation starts feeling sluggish or repetitive, use Compact conversation in the chat header's actions menu (⋯). It triggers the same summarization the runtime does automatically — your visible messages stay put, and it takes effect on your next message. Anything already in Memory is unaffected; for an unsaved detail that matters, ask the agent to remember it before you compact.
Subagent and cron sessions don't load MEMORY.md. Background and delegated sessions intentionally skip Memory to stay focused on their task. If a piece of knowledge needs to be available to every session — including cron jobs and subagents — it belongs in Instructions, not Memory. See the OpenClaw memory docs for the underlying filter logic.

Examples

Put in Instructions:

"Always answer in English, even if the user writes in another language."
"When the user asks for a deploy, run pnpm build, then docker compose up -d, in that order."
"You are the HR assistant for Acme Corp. Be warm and discreet."

Let Memory hold:

"Our quarterly board meeting is the first Friday of every quarter at 10:00 CET."
"Project IDs follow the format PRJ-NNNN."
"Clemens prefers shorter answers without bullet points."

Don't persist at all:

"For this conversation only, pretend you're reviewing a draft PR."
"Look at the file I just pasted and find the bug." (the file is in the chat already)

Editing each store

Instructions — open the agent's settings, then the Personality or Instructions tab.
Memory — talk to the agent. Say "remember this: …" to add an entry, or "forget …" to remove one. Auto-memory does most of the work without you having to ask.

For more on how memory is scoped between personal and shared agents (and what that means for privacy), see Understanding Agent Memory.

Upstream references

Pinchy runs on the OpenClaw runtime, which owns the underlying mechanics: