Your markdown folder, hosted and conflict-free.

If you've got a CLAUDE.md, an _markbase.md, or a context/ folder of markdown notes committed to a repo, you've already worked out the most important thing: agents want plain text in a predictable place.

Markbase isn't telling you to abandon that. It is that — just hosted, and made safe for multiple writers.

Where the folder pattern breaks

One agent, one machine: it works great. Claude Code reads CLAUDE.md, writes CLAUDE.md, Git tracks the change, you commit. Life is good.

Two agents on the same machine: it gets fragile. Two parallel agents both read the file, both edit it, both write it. The second write silently replaces the first agent's work. You only notice when something downstream breaks.

Two machines, or any remote agent: it stops working. A folder on disk isn't reachable. You can sync it, but now you've put an eventually-consistent file-sync system in front of an agent that expects a read to reflect the last write. Races, conflicts, and the agent has no way to know.

A hosted agent (Claude.ai, an MCP-aware service): impossible. There's no path short of exposing your filesystem on the public internet. Nobody should do that.

Your CLAUDE.md, but inside the memory

The CLAUDE.md / _markbase.md pattern is the other half of what you've already worked out: agents do better when you tell them how to use the memory. "Decisions go here, in this shape. Bug postmortems go there. Don't write to this folder unprompted." That's the right instinct.

The trouble is that file lives outside the memory it governs. It's a sibling on disk, replicated into each harness config, drifting between repos as conventions evolve. Add a second repo or a remote agent and you're maintaining the same set of rules in several places.

Markbase makes that pattern a property of the memory store itself. Every folder in your workspace can carry an _markbase.md: what this folder is for, what the frontmatter contract is, what's append-only. Agents read the chain root-to-leaf before they act on a path. Same shape you're already using — now in one canonical place, traveling with the data it describes.

Structure where the same shape keeps recurring

A grep-able folder is great until you're maintaining the same shape of record across fifty files by hand. Every decision needs a status, a date, a one-line summary; every postmortem needs a severity and an owner. The shape lives in your head and drifts agent by agent.

Markbase lets that shape live in the folder. Drop a _schema.md beside the records and the folder becomes a typed collection: agents append records that conform, and they can query the collection by field — last ten accepted decisions, open postmortems by severity — without grepping. Same .md files underneath; the contract is just YAML frontmatter.

What you learned in one repo is useful in the next

A CLAUDE.md is written for the repo it lives in. The architecture you worked out, the decisions you made, the gotchas you wrote down — they're exactly the kind of evidence that would be useful the next time you build something similar. But they're stuck where they were written. The next project starts with an empty CLAUDE.md and a blank slate.

Markbase keeps each project's memory in its own workspace, but an agent isn't confined to one. Ask it to design a feature in your new project and tell it to draw on the architecture decisions from your old one — same conversation, no clone, no copy-paste. What you figured out once becomes input to what you're building next.

Git solves a different problem

Git solves human conflicts after the fact: you both edit, you both push, the second push fails, a human reconciles.

Agents need conflicts prevented at write time. They don't get to go stare at a merge conflict and figure it out. They need the server to say "the document changed since you read it; here's the new version, try again" — and to handle that in a single tool call.

That's what ETags are for. Markbase's update_doc takes an if_match ETag from your last read_doc. If anything else wrote in between, you get a clean etag_mismatch back with the new ETag, and the agent re-reads and retries. No silent loss.