{"slug": "why-i-stopped-using-vector-rag-for-coding-agents-and-used-git-markdown-instead", "title": "Why I Stopped Using Vector RAG for Coding Agents (And Used Git Markdown Instead)", "summary": "A developer has proposed replacing vector-based RAG for coding agents with a Git-backed markdown system, arguing that topic-scoped .md files accessed via MCP provide deterministic context persistence without the overhead of embeddings. The approach uses a small index file to let agents fetch only relevant documentation, and updates are tracked in pull request diffs.", "body_md": "If you use Cursor, Claude Code, or Windsurf daily, you’ve probably hit this wall:\n\nYou spend 45 minutes explaining your architecture, your API contracts, and why you *never* use a certain library pattern. The agent gets it, writes great code, and you finish the feature.\n\n**Next morning, in a fresh session:**\n\n\"Let's implement this! I will use [the exact pattern you ruled out yesterday] and rebuild [a helper function that already exists].\"\n\nIt feels like babysitting a brilliant junior engineer with amnesia.\n\n`CLAUDE.md`\n\n/ `.cursorrules`\n\nDump\nThe first instinct is dumping every rule, schema, and architectural pattern into a project instructions file.\n\nThe second instinct is building or adopting a vector-based memory tool (embedding chunks of past chats/code).\n\nInstead of guessing via embeddings or overloading the system prompt, the cleanest architecture treats **agent memory like codebase documentation**:\n\n```\n.opencontext/\n├── architecture.md\n├── api-contracts.md\n├── state-management.md\n└── rejected-approaches.md\n[New Coding Session]\n│\n▼\n\n1. Agent queries MCP index (~100 tokens)\n(\"Available topics: architecture, api-contracts, state-management...\")\n│\n▼\n2. Agent fetches ONLY what it needs for the current task\n(e.g., read_context(\"api-contracts\"))\n│\n▼\n3. Agent writes code adhering to exact invariants\n│\n▼\n4. Architectural change? Agent mutates the markdown file in-place\n```\n\nInstead of dumping 15 KB of architectural docs into the system prompt, the agent starts every session with a tiny, auto-generated index:\n\n```\n{\n  \"topics\": [\"auth-flow\", \"error-handling\", \"database-conventions\"],\n  \"total_files\": 3\n}\n```\n\n*Cost: ~100 tokens.* The model calls `read_context(\"auth-flow\")`\n\n**only if** the prompt touches authentication.\n\nVectors fail because they append indefinitely. With topic-scoped markdown files, the agent updates the existing document when an architectural decision changes. **There are no competing versions in vector space.**\n\nBecause memory is just flat `.md`\n\nfiles inside the repository:\n\n`.opencontext/api-contracts.md`\n\n, it shows up directly in your GitHub pull request diff.You can connect a lightweight local MCP server to Cursor or Claude Code in seconds.\n\nIn your `claude.json`\n\nor Cursor MCP settings:\n\n```\n{\n  \"mcpServers\": {\n    \"opencontext\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"opencontext-mcp\"]\n    }\n  }\n}\n```\n\nNow, instead of re-explaining constraints, you can simply tell your agent:\n\n\"Check the database conventions in our context and scaffold the new user billing schema.\"\n\nThe agent checks the index, reads `.opencontext/database-conventions.md`\n\n, adheres to your patterns, and moves on.\n\nWe don't need complex vector pipelines for single-repository agent memory.\n\nPlain text in Git has been the source of truth for software engineering for 20 years. Giving agents deterministic read/write access to structured markdown via MCP solves context persistence without the overhead.\n\n**How are you currently preventing your coding agents from losing context across sessions? Are you sticking with static rule files, using RAG, or building internal tools?**", "url": "https://wpnews.pro/news/why-i-stopped-using-vector-rag-for-coding-agents-and-used-git-markdown-instead", "canonical_source": "https://dev.to/sluca/why-i-stopped-using-vector-rag-for-coding-agents-and-used-git-markdown-instead-4ob1", "published_at": "2026-08-30 21:38:22+00:00", "updated_at": "2026-08-30 22:22:38.963121+00:00", "lang": "en", "topics": ["developer-tools", "ai-agents", "large-language-models"], "entities": ["Cursor", "Claude Code", "Windsurf", "MCP", "opencontext-mcp"], "alternates": {"html": "https://wpnews.pro/news/why-i-stopped-using-vector-rag-for-coding-agents-and-used-git-markdown-instead", "markdown": "https://wpnews.pro/news/why-i-stopped-using-vector-rag-for-coding-agents-and-used-git-markdown-instead.md", "text": "https://wpnews.pro/news/why-i-stopped-using-vector-rag-for-coding-agents-and-used-git-markdown-instead.txt", "jsonld": "https://wpnews.pro/news/why-i-stopped-using-vector-rag-for-coding-agents-and-used-git-markdown-instead.jsonld"}}