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

A developer built Get Things Done, an open-source, local-first work memory for coding agents like Claude Code, Codex and GitHub Copilot that stores reviewed context as plain Markdown files with YAML frontmatter instead of in a database. Agents discover the memory through files they already read (CLAUDE.md, AGENTS.md, .github/copilot-instructions.md) with no MCP server or proprietary memory API, and meeting transcripts are transcribed locally with Whisper or SenseVoice so the agent proposes memory changes that a user must accept or reject. The developer acknowledges trade-offs including the need for a search index, harder structured queries than SQL, and no real locking between the dashboard and the agent.

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 https://github.com/geovanneb/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. 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 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. 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 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. 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: 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. 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 https://github.com/geovanneb/get-things-done/releases/latest . 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 https://github.com/geovanneb/get-things-done helps other people find it.