Why I chose plain Markdown over a database for AI agent memory

Bertonha — Wed, 04 Nov 2026 01:35:58 +0000

Every time I opened a new Claude Code session, I spent the first few minutes explaining my work again. Who the customer is. What we decided last week. How the weekly update should look. The agent was good at the task. It just knew nothing about the context around it.

So I built Get Things Done, an open-source, local-first work memory for Claude Code, Codex and GitHub Copilot. This post is about one design decision behind it: storing that memory as plain Markdown files instead of in a database.

What "memory" means here

Not model training. Not embeddings hidden behind an API. Memory here means reviewed context: notes about your projects, the people you work with, past decisions and the formats you deliver, written down somewhere your agent can read before it starts a task.

The layout

The whole workspace is a folder:

work-memory/
├── profile/          Your working style and preferences
├── stakeholders/     People, organizations and expectations
├── context/          Projects, decisions, risks and terminology
├── context-updates/  Material and proposed memory changes
├── meetings/         Retained recordings and transcript versions
├── outputs/          Reusable deliverable templates
└── tasks/            Objectives, deliverables and execution logs

Each file is Markdown with YAML frontmatter. Agents find it through files they already read: CLAUDE.md for Claude Code, AGENTS.md for Codex, .github/copilot-instructions.md for Copilot. No MCP server, no proprietary memory API.

Why Markdown

Agents already read files well. Coding agents are built to navigate a repository. A folder of well-named Markdown files is the shape of data they handle best, with no extra tool layer.

Humans can read and fix it. If the agent has a wrong idea about a stakeholder, I open the file and correct it. No admin UI, no query.

Git gives history for free. Put the workspace in a private repo and every change to your context is a diff you can review or revert.

No lock-in. If I switch from Claude Code to Codex tomorrow, the memory comes with me. It is just files.

The review step

The most useful part turned out to be how memory gets updated. Meetings are the main input: you record or import one, it is transcribed locally (Whisper or SenseVoice, after a one-time model download), and an agent compares it with what the workspace already knows.

The agent does not write to memory directly. It proposes changes, such as a new deadline, a changed decision or what a colleague expects, with the evidence from the transcript. You accept or reject each one. Only then does it become context for the next task.

I did not want an agent quietly rewriting what it "knows" about my work. A review step keeps the memory something I trust.

The hard parts

Plain files are simple until two writers touch the same folder. Here the dashboard and the agent both edit the workspace, so a few things matter:

Writes go through a temp file and a rename, so a reader never sees a half-written file. This does not stop two writers from overwriting each other's changes, and the docs say so.
Paths are validated at every service boundary, including values from JSON request bodies, so a crafted name cannot escape the workspace folder.
Search uses an optional SQLite index derived from the files. You can delete it at any time. The files stay the source of truth.
The dashboard binds to 127.0.0.1. Cloud agents still see what they read, which is worth being clear about.

Trade-offs

Markdown is not free. Search across many files needs an index. Structured queries ("every decision about project X since September") are harder than in SQL. And there is no real locking between the agent and the dashboard.

For a personal or small-team work memory, I think those costs are worth it. You own the data, you can read every byte of it, and any agent that can open a file can use it.

Try it

npm install -g @bertonha/getthingsdone
mkdir work-memory && cd work-memory
gtd init
gtd start

There is also a desktop app for macOS and Windows on the releases page.

I would love feedback: what context do you still find yourself repeating to your agent? And if this approach is useful to you, a star on GitHub helps other people find it.

DEV Community: Bertonha