Andrew Paul Simmons

PRODUCT ENGINEER

Feb 25, 2026 · 10 min read

I Built a Knowledge Base That My AI Can Actually Use

How a folder of markdown files became the most productive tool in my workflow

I have a folder on my computer. No code in it. No application, no database. Just markdown files organized into subdirectories: vision, products, technical architecture, research, marketing, decisions.

I can open that folder in Cursor and work on it with Claude the same way a developer works on a codebase or just open it in the Claude app and it instantly has full context. Either way, the AI reads the files, understands the project, and picks up where the last conversation left off.

This is my knowledge base. And it's become the most productive tool in my workflow.

It started because I kept hitting the same wall. Every new conversation with an AI was a cold start. I'd spend 2-3 minutes re-explaining context, and even then the new conversation never had the richness of the previous one. Throughout the session I'd keep hitting moments where I had to re-introduce something it should have already known. A decision we'd made, a tradeoff we'd weighed, a term we'd settled on. The conversations were good. But they were always thinner than the last one.

So I started writing things down in a format the AI could actually use. Not a wiki for humans. A folder of plain text files designed so an AI agent could get up to speed on my entire project in under 30 seconds.

The Setup

The repo is simple. Subdirectories for each domain: vision, products, technical architecture, research, marketing, decisions. Each file covers one topic. Each file starts with a one-line summary.

No database. No build step. No dependencies. Just .md files in folders, tracked by git.

The division of labor is straightforward. I work on the files I care about: vision documents, marketing copy, product strategy, blog posts. The agent creates and maintains everything else. It built the README and keeps it updated as files change. It maintains a conversation log, a decisions log, and a session index. In some chats it records every message. I never asked it to do most of this. It figured out that these files make its own job easier in future sessions, so it creates them.

When a new conversation starts, the agent reads the README first. From that single file it knows what exists, where to find it, and what each document covers. Then it reads only the files it needs for the current task.

How the Agent Actually Navigates It

This is the part that surprised me.

I assumed the agent would follow hyperlinks between documents, the way a human reads a wiki. Click a link, read that page, click another link, follow a trail. That's how I'd navigate it.

The agent doesn't do that at all. It searches.

When it needs information, it runs parallel keyword searches across every file in the repo simultaneously. If I ask about a specific concept, it greps for that term across all 30+ files and gets back a list of every file and line where it appears. Then it reads the relevant files in full, in parallel. Two tool calls and it has complete context.

This means the agent cares about two things: the README it created (so it knows what exists) and consistent terminology (so its searches return clean results).

That second point took me a while to understand. If I call the same concept "pattern matching" in one document, "regex layer" in another, and "deterministic parsing" in a third, the agent has to run three separate searches to find all references. If I always call it "regex layer," one search finds everything.

I started thinking of this as registered terminology. Every concept in the project gets one canonical name. I use that name everywhere. The agent's search becomes a lookup instead of a scavenger hunt.

The AI Writes, I Review

Here's the workflow shift that made this sustainable: I don't write most of the documents myself.

I describe what I need. The agent drafts the document based on our conversation and everything it already knows from the repo. I read the draft, make corrections, and approve it. The agent commits the file to git.

This applies to the documents I care about: product specs, blog posts, research summaries, marketing copy. I'm the editor, not the author. The AI does the mechanical work of translating a conversation into a structured document. I make sure it's accurate and sounds like me.

But beyond the documents I ask for, the agent maintains a whole layer of files on its own. Conversation logs, decision records, session indexes. One thing I noticed: it keeps every file under 500 lines without being asked. Nobody told it to do that. It just figured out that shorter files are easier for it to work with in future sessions, so it self-enforces the limit.

What It Replaced

Before the knowledge base, my workflow looked like this:

The knowledge base collapsed steps 1 and 2. Now I start a conversation, point it at the repo, and say "get up to speed." The agent reads the files it needs and is ready to work in seconds.

But the bigger change was less obvious. The knowledge base became the canonical record of every decision, every research finding, every piece of strategy. Before, that stuff lived in chat transcripts that nobody would ever re-read. Now it lives in files that are searchable, diffable, and version-controlled.

The agent maintains the decisions log. When we make a call during a conversation, the agent writes it down with the date and the reasoning. When a new conversation starts weeks later and I ask about that topic, the agent finds the decision. It doesn't re-derive it from first principles. It reads what we already decided and builds from there.

How I Started the Knowledge Base

Before the knowledge base existed, I had a master thread. One long conversation in Claude that I kept going back to. It started as a place to generate prompts for other agents, but over time it became something bigger. I discussed every aspect of the project in that thread: product decisions, technical architecture, marketing angles, competitive research. It became the recording of my own thinking, a way to work through problems out loud with an AI that remembered the full history.

For a while, that worked well. The thread became my project brain. Whenever I needed to spin up a new agent for a specific task, I'd go back to the master thread, generate a detailed prompt with all the relevant context, and paste it into a fresh conversation.

But eventually the thread got too big. Scrolling back to find a decision from two weeks ago took forever. Generating prompts for new agents meant re-reading sections of a massive conversation to pull out the right context. And I kept needing to launch multiple agents at once, each working on a different part of the project, all needing full context immediately. The master thread couldn't scale to that.

So I asked Claude to package everything up: the entire conversation, plus all the documents we'd built together over the previous few weeks to define product features, scope, and research. It pulled out every topic, decision, spec, and concept, organized them into subdirectories, created a README, and gave me a zip file. I dropped that folder into a git repo, opened it in Cursor, and started iterating from there.

The knowledge base is what the master thread wanted to be. Same content, same context, same history. But now any agent can read it in 30 seconds instead of scrolling through thousands of lines of conversation. I can launch five agents in parallel and they all have full context immediately. No prompt generation, no copy-pasting from an old thread. Just "read the repo."

One thing I'd do from the start next time is create a terminology registry with the AI. A single file that lists the canonical name for every concept in the project. Then I'd have the agent add a note to its own context documents that it should hold me to that registry. If I slip and call something by the wrong name in a new document, the agent catches it and corrects it. That problem compounds fast. Twenty documents with three names for the same concept is a mess to clean up later. Better to have the AI enforcing consistency from day one.

Why Markdown, Why Git

People ask why I don't use Notion or Confluence or some purpose-built tool.

Markdown is plain text. Every AI model can read it natively. No API integration, no export step, no formatting translation. The agent reads the file directly. I can open it in Cursor, in the Claude app, or in any text editor.

Git gives me version history for free. I can see when a decision changed, what the previous version said, and who (or what) wrote it. When the agent drafts content, I review the diff before committing. The repo is the collaboration layer between me and the AI.

The Takeaway

The best thing I did for my AI workflow wasn't finding a better model or writing better prompts. It was giving the model something to remember.

A knowledge base built for AI consumption turns every new conversation from a cold start into a warm handoff. The agent reads, searches, and picks up where the last conversation left off. The AI writes the documents, maintains the files, and tracks the decisions. I steer and review.

If you're doing serious work with AI and you're still relying on chat history to carry context, try this instead. Have a long conversation about your project. Then use the prompt below to turn it into a knowledge base. Drop the folder into a git repo, open it in Cursor or the Claude app, and start working.

Starter Prompt

Paste this at the end of a long conversation to seed your knowledge base:

Review everything we've discussed in this conversation. Create a downloadable folder of organized markdown files that captures the full project as a knowledge base. Include: This folder will be opened in Cursor or the Claude desktop app as a persistent knowledge base for future sessions. Optimize it for an AI agent that will search by keyword, not follow links.