Give your AI agent persistent memory using nothing but markdown files.
This is the system from the video: My AI and I Share a Brain — Here's How I Built It
A set of template files that create a "shared brain" between you and your AI agent. You both read and write to the same files. Over time, the agent builds genuine context about you, your work, and your preferences — without databases, fine-tuning, or custom code.
You need an AI agent that can read and write files on its own. This won't work with ChatGPT or Claude's web interface — they can read uploads but can't write back to a file system.
Tools that work:
- OpenClaw — what I use (persistent agent with file access, messaging, tools)
- Claude Code — Claude with full file system access
- Codex — OpenAI's coding agent
- Cursor / Windsurf — AI-native code editors with file access
Any system where the AI can read files, write files, and persist them between sessions will work.
Every agentic tool has a folder where your AI agent operates — the directory it can read from and write to. This is its workspace:
| Tool | Default workspace |
|---|---|
| OpenClaw | ~/.openclaw/workspace/ |
| Claude Code | Whatever directory you launch it in (cd my-project && claude) |
| Codex | The project directory you open it in |
| Cursor / Windsurf | The folder you have open in the editor |
The shared brain files need to live inside that workspace so the agent can access them.
Option A: Clone with Git (if you have Git installed)
Open a terminal and navigate to your agent's workspace, then clone:
# Example for OpenClaw:
cd ~/.openclaw/workspace
git clone https://github.com/Jason-Cyr/ai-shared-brain.git .
# Example for Claude Code — make a new project folder, then launch Claude in it:
mkdir ~/ai-shared-brain
cd ~/ai-shared-brain
git clone https://github.com/Jason-Cyr/ai-shared-brain.git .
claudeOption B: Download manually (no Git needed)
- Click the green "Code" button on this GitHub page
- Click "Download ZIP"
- Unzip the files into your agent's workspace folder
Option C: Copy the files by hand
If you'd rather start from scratch, create these files in your agent's workspace:
SOUL.mdUSER.mdAGENTS.mdMEMORY.md- A
memory/folder (empty — the agent creates daily notes here)
Use the templates in this repo as a starting point.
- Edit
USER.md— Fill in your name, timezone, role, and preferences - Edit
SOUL.md— Shape the agent's personality (or keep the default — it's a good start) - Review
AGENTS.md— This is the operating manual. The startup ritual at the top is what makes everything work. - Leave
MEMORY.mdalone — It starts mostly empty. The agent fills it over time. - Start a session with your agent. It should read the files and begin building context.
- Give it a few days. The memory folder and MEMORY.md will fill up on their own.
ai-shared-brain/
├── SOUL.md # Layer 1: Agent identity — personality, boundaries, voice
├── USER.md # Layer 1: Your identity — who the agent is helping
├── AGENTS.md # Layer 1: Operating manual — startup ritual, rules, behavior
├── MEMORY.md # Layer 2: Long-term memory — curated by the agent over time
├── memory/ # Layer 3: Episodic memory — daily notes (agent creates these)
│ └── .gitkeep
├── LICENSE # MIT — use however you want
└── README.md
SOUL.md — Who the agent is. Personality, communication style, boundaries. USER.md — Who you are. Name, timezone, role, preferences. So the agent doesn't have to ask. AGENTS.md — The operating manual. What to read on startup, when to write things down, how to behave.
MEMORY.md — Starts empty. The agent fills it over time with curated knowledge: key decisions, project context, your preferences, lessons learned. Think of it as the agent's distilled understanding of your world. The agent periodically reviews daily notes and promotes important things here.
memory/YYYY-MM-DD.md — Daily notes. The agent creates one each day and logs what happened: what you worked on, decisions made, things to follow up on. These are the raw material that feeds long-term memory.
Connect your own knowledge base — Obsidian vault, Notion workspace, project folders, whatever you use. The agent reads from it to get real-time context on your work. This layer is yours to configure based on your setup.
The entire system works because of one instruction in AGENTS.md:
Before doing anything, read SOUL.md, USER.md, today's daily note, yesterday's daily note, and MEMORY.md.
That startup ritual is what creates continuity between sessions. Without it, the files are just files. With it, they're a shared brain.
- Give it time. The system gets dramatically better after 2-3 weeks as memory accumulates.
- Read MEMORY.md yourself. It's a plain text file. You can see exactly what your AI "knows" about you. Correct it. Delete things. There is no black box.
- The agent should write things down, not keep "mental notes." If it doesn't write to a file, it won't remember next session.
- Start simple. A few lines in each file is enough. You'll naturally add more over time.
Found a way to make this better? PRs welcome. This is meant to be a starting point that people adapt to their own workflows.
MIT — use it however you want.
Built by Jason Cyr — VP Design at Cisco, building AI systems for real work.
- YouTube: @Jason_Cyr
- LinkedIn: jasncyr
- Substack: jasoncyr.substack.com