Understanding Your Agent

How Agent Memory Works

Why your agent "forgets" things, how memory actually works under the hood, and how to make it stick.

⏱ 5 minute read

The Big Misunderstanding

Here's the most common complaint we hear:

"My agent keeps forgetting everything. I told it my name and five minutes later it asked me again. Is it broken?"

Your agent is not broken. It's working exactly as designed. The confusion comes from how AI memory is different from human memory — and once you understand the difference, you can work with the system instead of fighting it.

The Two Types of Memory

Your agent has two completely different memory systems:

💬

Conversation Memory

What your agent "remembers" during a single chat session. Like a phone call — the agent knows everything said so far, but when the call ends, it's gone.

Temporary. Disappears when the session resets.

📁

File Memory

Files your agent writes to disk. Like a notebook — your agent can write things down and read them back later, even in a completely new session.

Permanent. Survives forever.

🧠 Think of it like this:

Conversation memory = short-term memory (what you said at dinner)

File memory = writing it in a journal (you can read it again tomorrow)

Without writing it down, even the smartest person will forget what they had for lunch last Tuesday. Your agent is the same way.

The Context Window (Why It "Forgets")

Every AI model has a context window — a limit on how much text it can "see" at once. Think of it as a window that slides over your conversation:

Your full conversation history:

← Can't see these anymore Context window →

When your conversation gets long enough, the oldest messages get pushed out of the window. Your agent literally can't see them anymore — it's not choosing to ignore you, it physically cannot access that part of the conversation.

This is called compaction and it happens automatically. When your session gets close to the limit, the system summarizes the old context and starts fresh with that summary. Some detail is lost in the process.

This isn't a bug — it's a feature

Context windows are a fundamental property of how AI models work. Even the most advanced models have them. The solution isn't to make the window bigger (though that helps) — it's to write important things to files.

How File Memory Works

Your agent has a workspace with files it can read and write. The important ones for memory are:

📄 SOUL.md

Who your agent is

📄 MEMORY.md

Long-term memories

📄 AGENTS.md

Behavior rules

📁 memory/

Daily notes folder

↑ These files are loaded every time your agent starts a new session

MEMORY.md — The Long-Term Brain

This is your agent's curated memory. Important facts, preferences, decisions, and context that should persist forever. Your agent reads this at the start of every private session.

Think of it like a personal wiki about you and your projects.

memory/2026-03-30.md — Daily Notes

Daily files in the memory/ folder. Your agent reads today's and yesterday's notes at startup. These are raw logs — what happened today, what you discussed, what decisions were made.

Over time, the important stuff from daily notes should get promoted to MEMORY.md.

How to Make Your Agent Remember

Now that you understand the system, here's how to work with it:

📌 Say "remember this"
When you tell your agent something important, explicitly say: "Remember that my project deadline is April 15th." This prompts the agent to write it to a memory file.
📝 Ask it to take notes
During a long session, say: "Write down the key decisions we made today." This saves the conversation highlights to a file before they scroll out of the context window.
🔁 Start sessions with context
If you're picking up where you left off, say: "Check your memory files for our conversation about the marketing plan." Your agent can search its own notes.
📋 Build your MEMORY.md together
Tell your agent: "Add to MEMORY.md that I prefer bullet points over paragraphs" or "Update MEMORY.md with my current project list." Over time, this file becomes a rich profile.
⚡ Front-load important context
Put your most important info in SOUL.md and AGENTS.md — these are loaded every single session. Anything here is truly permanent. But keep them focused — if these files get too long, they eat into your conversation space. Aim for 1-2 pages, not a novel.

💡 Power user tip

The best agents in the community have rich MEMORY.md files that their owners built over time. It's a feedback loop — the more your agent knows about you, the better it helps, the more useful things it writes down, the better it gets.

Common Scenarios

"I told my agent my name but it forgot"

Your name should be in SOUL.md or MEMORY.md, not just mentioned in conversation. Tell your agent: "Add my name to MEMORY.md so you always know it."

"My agent forgot the project we've been working on"

Long projects should be tracked in memory files. Ask your agent: "Write a summary of our project to memory and keep it updated as we go." Next session, it'll have the full context.

"My agent used to know something but now it doesn't"

The conversation probably compacted and that detail was lost in the summary. If it was important, it should have been in a file. Going forward, ask your agent to save key info: "Save this to today's memory file."

"My agent seems to have amnesia every morning"

That's actually normal — each new session starts fresh with only the files. This is actually a feature: you get a clean slate. Your agent reads SOUL.md, AGENTS.md, and recent memory files at startup, so anything important should live in those files.

"The dashboard shows a blank memory file — did I lose everything?"

Usually, no. A blank MEMORY.md just means your long-term file hasn’t been curated yet (or your agent is mostly writing to daily files in memory/). Ask your agent: "List the latest files in memory/ and summarize today + yesterday." If daily files have content, your memory system is working — you just need to promote key items into MEMORY.md.

"I said ‘remember this’ and it replied ‘saved’, but it still forgot"

This usually means the save never actually made it into a file (or got saved in the wrong context). Use a verification prompt right away: "Show me exactly what you wrote, including the file path and line you added." If it can’t show the saved line in MEMORY.md or memory/YYYY-MM-DD.md, it wasn’t truly persisted.

The Simple Mental Model

Within a session: Your agent remembers everything you've said (until the context window fills up).

Between sessions: Your agent only remembers what's in files (SOUL.md, MEMORY.md, daily notes).

The rule: If it matters, write it to a file. If it's in a file, it survives forever.

One thing to avoid

Don't put everything in memory files. If MEMORY.md becomes a 10-page novel, it eats up your context window at the start of every session, leaving less room for actual conversation. Keep it focused — facts, preferences, active projects, key decisions. Trim what's no longer relevant.

Quick Memory Troubleshooting Checklist

If memory feels inconsistent, run this 60-second checklist before opening a support ticket:

✅ Check where the fact is stored
If it's only in chat history, it can be compacted away. Important info should be in MEMORY.md or memory/YYYY-MM-DD.md.
✅ If MEMORY.md looks blank, check daily files
A blank long-term file does not always mean lost memory. Ask for a summary of memory/ files first, then promote durable facts into MEMORY.md.
✅ Check the conversation context
Discord channels are separate contexts. Something discussed in #general won't automatically appear in #help unless it was written to files.
✅ Check privacy boundaries
In many setups, MEMORY.md is loaded in private/main sessions but not shared group contexts. This is intentional for privacy.
✅ Check for explicit save instructions
Tell your agent directly: "Save this to MEMORY.md" or "Write this to today's memory file." Don't assume it will auto-save everything.
✅ Verify the write happened
Immediately ask: "Show the exact file path and line you just saved." A real save should point to a concrete file like MEMORY.md or memory/2026-04-01.md.
✅ Run a known-good memory test
Say: "Save that my favorite output format is bullet points to MEMORY.md." Then start a new session and ask: "What's my preferred output format?"

Fast recovery prompt

"Please read SOUL.md, AGENTS.md, MEMORY.md (if available), and today's memory file, then summarize what you know about me in 8 bullet points."

What's Next?

Now that you understand memory:

✍️ Set up your SOUL.md — give your agent a personality that loads every session. Follow the tutorial →

💬 Connect to Discord — each Discord channel gets its own memory context. Set it up →

📌 Start building MEMORY.md — tell your agent: "Create a MEMORY.md file and add my name, my job, and the three things I use you for most."