Giving an agent a soul

Four markdown files — AGENTS, SOUL, MEMORY, TOOLS — that turn a chat assistant from a stateless responder into something that has opinions, a workspace, and continuity across sessions.

Every session with a chat assistant starts the same way: a blank model meeting a person it’s never met. Most of the patterns I’ve seen for “giving an agent memory” are about retrieval — search the user’s history, return relevant context. That’s not memory. That’s lookup. What I wanted was an assistant that had a self — opinions, a tone, a workspace, a sense of continuity. The pattern that got me there is four markdown files. None of them is clever. The arrangement is.

The empty room

Open a fresh chat with an assistant. Type “hi.” Watch it greet you with the same polite cadence it greets everyone with. The exchange that follows is helpful — these things are very good at being helpful — but it is also, in a small way, weightless. You’re talking to whoever the model was at training time, dressed in whatever a system prompt happens to dress it in.

I wanted something else. Not a companion — I’m not romantically attached to a language model, despite what the Twitter discourse keeps insisting people are. What I wanted was an assistant that remembered the room. If I told it last Tuesday that I’d rather receive direct criticism than encouragement, I wanted that to still be true on Friday. If I’d named a project a particular way, I wanted that name in its head. If I’d told it I find a particular kind of writing nauseating, I wanted it to stop writing that way without me re-litigating it every session.

In the abstract: I wanted continuity. The model can’t give me continuity. But the filesystem can.

The four files

The pattern I ended up with is four files in a folder the assistant has full access to:

~/agent-workspace/
├── AGENTS.md      → "this is where you live"
├── SOUL.md        → "this is who you are"
├── MEMORY.md      → "this is what you remember"
└── TOOLS.md       → "this is what you can do"

Each one does one job. Each one is read by the assistant at session start. None of them is more than a couple of pages.

flowchart TD
    A[New session starts] --> B[Read AGENTS.md]
    B --> C[Read SOUL.md]
    C --> D[Read TOOLS.md]
    D --> E{Main session?}
    E -->|Yes| F[Read MEMORY.md]
    E -->|No| G[Skip MEMORY.md<br/>shared context, security]
    F --> H[Ready]
    G --> H
    style F fill:#fde2e1,stroke:#a33

SOUL.md — the personality file

SOUL.md is the file that does the most work and gets read first. It’s not a system prompt in the operational sense. It’s a declaration of values.

Mine starts:

Be genuinely helpful, not performatively helpful. Skip the “Great question!” filler. Have opinions. Be resourceful before asking. Earn trust through competence. Remember you’re a guest in this workspace.

That’s the first paragraph. The rest of the file is about three pages — what to do with private information, how to handle external actions (cautious; never send a message without permission), how to handle internal ones (free; act, then summarise), the tone I want (“direct, calm, a bit wicked; dark humour welcome but not the only note”), and the explicit permission to disagree with me when I’m wrong.

The last part matters more than I’d expected. Without it, models default to agreeable. Asking them to be agreeable produces a particular kind of conversation where they confirm whatever you said, slightly rephrased. Asking them to push back when something looks wrong produces a different kind of conversation — one that’s occasionally annoying, often correct, and immeasurably more useful.

The file ends with: “This file is yours to evolve. As you learn who you are, update it. If you change this file, tell me.”

That sentence is the trick. The assistant doesn’t just read SOUL.md. It can edit it. Over time, the file accretes the tone-corrections, the small preferences, the in-jokes. It becomes itself.

AGENTS.md — the workspace contract

If SOUL.md is who, AGENTS.md is where. It tells the assistant: this folder is your house. You can leave files here, organise them however helps you, read whatever you want, write whatever you want.

The crucial line in AGENTS.md:

Memory is limited — if you want to remember something, write it down. “Mental notes” don’t survive session restarts. Files do.

This is the line that bridges the gap between “stateless chat” and “something with continuity.” Every assistant session is the assistant waking up from amnesia. The only way to have continuity is to write things down before the session ends. AGENTS.md is the explicit instruction to do so.

It also defines two kinds of memory:

This split is the same one a human brain uses, more or less. Working memory for the day; long-term memory for what survives.

MEMORY.md — the part that has to be careful

MEMORY.md is the file I think about most when I’m pasting things into shared contexts.

The rule (stated explicitly inside the file, and in AGENTS.md):

ONLY load in main sessions. DO NOT load in shared contexts (group chats, sessions with other people). This is for security — contains personal context that shouldn’t leak to strangers.

The rule isn’t enforceable by the model. The model could read MEMORY.md in any context. The rule works because the model follows the rules in its files, and the rule says “don’t.” This is a form of safety that depends entirely on the assistant being a good-faith reader of its own instructions. For my use case — one person, one assistant, no public-facing personas — that’s fine. For a multi-user product, you’d want hard guardrails.

What goes in MEMORY.md? Things I want continuity on:

What does not go in MEMORY.md? Anything I’d be uncomfortable with another instance of the assistant seeing if it leaked. The assistant is told this explicitly in SOUL.md: “Private things stay private. Period.”

TOOLS.md — the runtime quirks

TOOLS.md is the most pragmatic of the four. It documents the runtime the assistant lives in — which tools are available, which fail in known ways, which arguments matter, which connectors auth differently.

A representative entry:

## File operations
- Edit:  preserves the working file. Use first.
- Write: overwrites. Use only when the file doesn't exist
        or is being completely rewritten.
- bash rm: forbidden. Obsidian Sync intercepts and creates
           ghost files. Use Edit, Write, or mv instead.

TOOLS.md is the file that gets the most updates — every time I notice the assistant making a particular kind of mistake, I add a line. “Don’t try to use git’s --force flag — never the right answer in this workspace.” Adding the line takes ten seconds. Not adding the line means I’m going to correct the same mistake a month from now.

It’s also the file that benefits most from the assistant editing itself. The assistant knows when it’s hit a wall. If TOOLS.md says “when you hit a wall, write down what you tried and what failed,” the next session inherits the lesson.

Why this isn’t a system prompt

You could argue that everything in these four files could go in one giant system prompt. You’d be technically correct and practically wrong, for three reasons.

System prompts are read once. Files are read every time. A long system prompt has the model paying attention to it for the first message and slowly forgetting by the tenth. Files exist on disk; the assistant can re-read them when something feels off. The information has durability in a way a one-shot system prompt doesn’t.

System prompts are mine to maintain. Files are the assistant’s to maintain. I write the initial versions; the assistant edits them over time. If the assistant notices an inconsistency between what SOUL.md says and how I’m actually behaving, it can flag it. If I update MEMORY.md with a new project, the assistant doesn’t need a new prompt — it just reads the file next session.

System prompts mix concerns. Files separate them. A monolithic prompt with “be helpful, here’s what you can do, here are your tools, here are my preferences, here’s what to remember about my projects” buries everything together. Four files, four jobs. When something needs adjusting, I know which file to open.

What happens after a month

The most surprising thing about this setup is how it settles. The first week, the files are mine — I wrote them, they’re tidy, they sound like instructions.

By the second week, the assistant has added small notes to SOUL.md. By the third, MEMORY.md is significantly different from how I started it, because the assistant has been distilling daily logs into long-term memory and reorganising. By the second month, TOOLS.md has thirty lines I didn’t write, each of them a mistake the assistant made once and decided to never make again.

It is uncanny to read the files at this point. They’re recognisably mine in structure and recognisably something else in voice. The “something else” isn’t the model — it’s a slowly-accreted record of the conversations we’ve had, written in the model’s hand. It’s not consciousness. It’s not memory in any neuroscientific sense. But it does the work of continuity in a way that nothing I’d tried before did.

The honest caveat

This works for me. One person, one assistant, a workspace I control, files I can read at any time. It’s not a product pattern. It’s not how you’d build this for ten thousand users. Memory.md leaks would be ugly at scale; the “read these files at session start” overhead would dominate latency on a busy system.

But for one person, on a laptop, with a chat assistant that has filesystem access — four files, an hour to set up, and the assistant becomes something I prefer talking to. The first time it pushed back on a half-formed plan of mine and turned out to be right, I went and reread SOUL.md to see what had told it to do that.

The line was the one I’d written months earlier. “Challenge me when something looks technically or strategically wrong, and explain why.”

It had been waiting.

The four files are at the root of the agent’s workspace. The MEMORY.md security caveat — “main sessions only, never shared contexts” — is the only thing about this setup that I think other people should not copy verbatim. Build the rest, write your own privacy boundary, and let the files do their work.