# CLAUDE.md, Obsidian, Markdown Files, and Why Workarounds Don't Scale for Teams > Source: > Published: 2026-05-29 02:05:39+00:00 Every team using AI coding tools has invented their own version of the same hack. Some put everything in CLAUDE.md and commit it to the repo. Some maintain shared Obsidian vaults. Some have a `context/` folder full of markdown files that someone updates when they remember to. Some paste a summary prompt at the start of every session. Some just re-explain everything every time and accept the tax. These all work, kind of, for one person. They all break the moment you add a second person or a second tool. I've used all of these workarounds and eventually built [Context Cloud](https://contextcloud.pro) because none of them actually solved the problem. Here's what I learned about each one. CLAUDE.md is the closest thing Claude Code has to a built-in persistence layer. It gets loaded at the start of every session and gives Claude persistent context about your project. Anthropic recently added auto-memory, where Claude writes its own notes based on corrections and preferences. **What it does well:** CLAUDE.md is great for static instructions. "Use TypeScript strict mode." "Run tests with `pnpm test` ." "The API is at `localhost:3001` ." These are things that don't change session to session, and CLAUDE.md handles them perfectly. It lives in your repo, it's version-controlled, and every session reads it automatically. **Where it breaks:** CLAUDE.md is not memory. It's a config file. Here's the difference: Memory is dynamic. It grows from sessions. "We tried Redis for caching but the latency was worse than Postgres for our query patterns — decision: stick with Postgres query cache." That came out of an hour-long debugging session. It's the kind of insight that should persist and be available to anyone who touches the caching layer. Putting it in CLAUDE.md means manually writing it up, committing it, and hoping your teammate pulls before their next session. Memory has attribution. When your teammate reads a decision in CLAUDE.md, there's no way to know who put it there, when, or why — unless they wrote a detailed commit message (they didn't). Was this decision made last week or six months ago? Is it still valid? Who do I ask about it? Memory has structure. In CLAUDE.md, everything is flat text. A critical architecture decision sits next to a linting preference. There's no way for the AI to know "this is a settled decision with specific rationale" versus "this is a temporary note about the current sprint state." It all gets treated the same. Memory has search. CLAUDE.md is one file. As it grows, it becomes a wall of text that Claude reads in full at the start of every session, eating context window for things that aren't relevant to the current task. There's no semantic search, no way to query "what do we know about the payment service?" and get back just the relevant chunks. And the real problem: **CLAUDE.md doesn't work across tools.** It's Claude Code only. If your teammate uses Cursor, they have .cursorrules, which is a completely separate file with separate syntax and separate limitations. If someone uses Codex, they have neither. There's no shared layer. Some teams connect Obsidian to their AI tools via MCP plugins. The idea is solid — Obsidian has great search, graph visualization, and a plugin ecosystem. Use it as the knowledge store, connect it to Claude or Cursor, and you have persistent memory with a nice UI. **What it does well:** Obsidian is a genuinely good personal knowledge tool. The graph view gives you visual structure. The search is fast. Plugins extend it in every direction. If you're already an Obsidian user, adding an MCP connector feels natural. **Where it breaks:** Obsidian is personal by design. Your vault lives on your machine. Making it "shared" means either: Beyond the sharing problem, Obsidian has no knowledge typing. A note is a note. There's no semantic difference between a decision and a finding and a convention. No attribution per note. No deduplication. And the MCP plugins are community-maintained with varying quality — they're not designed for the team use case. The power-user trap is real: you spend hours setting up Obsidian + plugins + sync + folder structure + tagging conventions, and at the end you have a system that works for you but that nobody else on the team wants to maintain. The most common workaround I see: a `docs/` or `context/` folder in the repo with markdown files that describe the project's architecture, decisions, and conventions. Sometimes it's an ADR (Architecture Decision Record) folder. Sometimes it's a single `ARCHITECTURE.md` file. **What it does well:** It's version-controlled. It's visible to the whole team. It doesn't require any new tools. Every developer already knows how to read and write markdown. **Where it breaks:** The maintenance problem is brutal. Documentation written by humans goes stale the moment it's committed. The decision you documented in `docs/decisions/003-database-choice.md` three months ago might no longer reflect reality, but nobody updated it because nobody remembers it exists. There's no search beyond grep. When your AI needs to know about the payment service, it can't semantically query your docs folder — it reads all of it or none of it. And reading all of it burns context window on irrelevant content. There's no automatic extraction. Every piece of knowledge in those markdown files was manually written by a developer who stopped coding to write documentation. We all know how often that happens. The reason AI memory servers exist is precisely because developers don't maintain documentation reliably. And there's no attribution, no typing, no deduplication, no temporal awareness. It's text files in a folder. Better than nothing, but not by as much as you'd hope. Same concept as CLAUDE.md, but for Cursor and Windsurf respectively. Same strengths (persistent project-level instructions, lives in the repo). Same weaknesses (static, unstructured, manual, no search, no attribution). The additional problem: these are tool-specific. Your .cursorrules don't help your teammate who uses Claude Code. Your CLAUDE.md doesn't help the person on Cursor. If your team uses multiple AI tools — and most teams do — you're maintaining separate config files for each one with no shared layer. Some teams try to solve this by maintaining all three files and keeping them in sync manually. This is exactly the kind of work that should be automated. "Just put it in Notion" is the suggestion that sounds reasonable until you try it. The problem isn't that Notion is bad. It's that Notion is disconnected from your AI sessions. Your Claude Code session can't read your Notion workspace (without a separate MCP integration). Your team's AI doesn't know about the decisions documented in Confluence. The knowledge exists, but it's not in the loop. Some MCP plugins connect Notion to AI tools, which helps. But Notion wasn't designed as an AI memory store. There's no typed knowledge structure, no session attribution, no deduplication, no semantic search tuned for the kind of short, decision-oriented chunks that AI sessions produce. You're fighting the tool's design instead of working with it. After trying all of these, here's what I think the solution actually needs: **Automatic extraction.** The AI does the work, not you. When you make a decision, the AI extracts it as a typed chunk — you don't stop coding to write documentation. **Typed knowledge.** Decisions are different from state which is different from conventions. The system should know the difference so it can treat a settled architecture decision differently from a temporary sprint status update. **Shared across teammates with attribution.** Not "commit and push and pull." Just shared. Person A commits, Person B's next session has it. With clear tracking of who committed what and when. **Searchable.** Not ctrl+F over a flat file. Semantic search (vector + keyword) that can handle natural language queries like "what do we know about the auth module?" **Cross-tool.** Works in Claude Code AND Cursor AND Codex. One shared knowledge layer, accessible from any AI tool. **A dashboard.** Someone needs to be able to see the full picture — what's been committed, what's stale, what's contradictory. A knowledge graph, not a folder of text files. This is what I built [Context Cloud](https://contextcloud.pro) to be. It's an MCP memory server with shared team workspaces, typed knowledge chunks (decision, finding, convention, state, question, reference), role-based access, and cross-tool support for Claude, Cursor, and Codex. CLAUDE.md and these workarounds aren't bad. They're fine for solo developers on small projects. If you're one person working on one project in one tool, CLAUDE.md plus maybe Basic Memory or claude-mem will get you 80% of the way there. The moment you add a second person or a second tool, they collapse. That's not a criticism of these tools — they weren't designed for teams. They were designed for individual persistence, and they do that well. The team problem is a different problem. It needs shared infrastructure, not shared files. That's the gap I'm building to fill. **Context Cloud** is an MCP memory server with shared team workspaces, typed knowledge chunks, role-based access, and cross-tool support for Claude, Cursor, and Codex. Free to use. `https://api.contextcloud.pro/mcp/protocol`