Erkle vs. CLAUDE.md
CLAUDE.md is a Markdown file that Claude Code loads into context at the start of every session. It's the right place for a repository's basics: how to build and test, how the code is laid out, which conventions to follow.
Erkle is for the knowledge that doesn't fit in one file in one repo: decisions and constraints that span repositories, lessons one person's agent learned that a teammate's agent needs, and anything people should review before agents treat it as a rule. Most teams use both.
// facts checked
## side-by-side
CLAUDE.md and Erkle, compared
| dimension | CLAUDE.md | Erkle |
|---|---|---|
| Where it lives | A file in each repo, plus personal files on each machine | One hosted memory for the whole team |
| Which agents read it | Claude Code | Any MCP client: Claude Code, Cursor, Codex, claude.ai |
| Across repositories | Copied or linked by hand | Team and project scopes reach every repo in them |
| How it loads | The whole file, every session, relevant or not | Searched per task: at most 8 results, about 4,000 tokens |
| Who can change it | Anyone who can merge to the repo | Maintainers write directly; contributors' writes wait for review |
| History | Git history of the file | Every memory versioned, with author, agent, and source URL |
| Agents adding knowledge | Edit the file, then land a PR | Write a memory over MCP; it becomes a proposal or goes live |
| Secrets | Whatever reviewers catch | Secret guard rejects writes containing keys or tokens |
| Price | Free | $5 per user per month or $50 per year, after a 7-day trial |
## use-both
Where each one fits
Keep in CLAUDE.md
- Build, test, and lint commands
- Repository layout and where things go
- Code style that applies to every change
- A line telling Claude to search Erkle first
Put in Erkle
- Constraints that cross service boundaries
- Decisions, with the reason and a link to the PR or ADR
- Lessons from incidents and dead ends
- Anything Cursor, Codex, or a teammate's agent also needs
# CLAUDE.md ## Commands - `npm test` runs against real Postgres. ## Team memory - Search Erkle before starting a task, and propose what you learn after.
## faq
claude-md --help
? Does Erkle replace CLAUDE.md?
No. CLAUDE.md is still the best place for a repo's basics that every session needs. Erkle holds the knowledge that is shared across repos, people, and tools, and returns only what's relevant to the task at hand.
? Can Claude Code use CLAUDE.md and Erkle together?
Yes. Claude Code loads CLAUDE.md at the start of the session and calls Erkle through MCP when it needs team knowledge. A line in CLAUDE.md asking it to search Erkle before each task makes that a habit.
? How do we move existing CLAUDE.md content into Erkle?
Connect Claude Code to Erkle and ask: "Import this repo's CLAUDE.md, docs, and ADRs into Erkle." It sends up to 100 memories per call and reports each result, including anything the secret guard rejected.
? Why not just keep one big CLAUDE.md?
Every line loads on every session whether or not it's relevant, other tools don't read it, other repositories don't see it, and there's no review step for what an agent adds. It works well up to a point, and that point is usually a second repo or a second tool.