# Why I Stopped Using Vector RAG for Coding Agents (And Used Git Markdown Instead)

> Source: <https://dev.to/sluca/why-i-stopped-using-vector-rag-for-coding-agents-and-used-git-markdown-instead-4ob1>
> Published: 2026-08-30 21:38:22+00:00

If you use Cursor, Claude Code, or Windsurf daily, you’ve probably hit this wall:

You 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.

**Next morning, in a fresh session:**

"Let's implement this! I will use [the exact pattern you ruled out yesterday] and rebuild [a helper function that already exists]."

It feels like babysitting a brilliant junior engineer with amnesia.

`CLAUDE.md`

/ `.cursorrules`

Dump
The first instinct is dumping every rule, schema, and architectural pattern into a project instructions file.

The second instinct is building or adopting a vector-based memory tool (embedding chunks of past chats/code).

Instead of guessing via embeddings or overloading the system prompt, the cleanest architecture treats **agent memory like codebase documentation**:

```
.opencontext/
├── architecture.md
├── api-contracts.md
├── state-management.md
└── rejected-approaches.md
[New Coding Session]
│
▼

1. Agent queries MCP index (~100 tokens)
("Available topics: architecture, api-contracts, state-management...")
│
▼
2. Agent fetches ONLY what it needs for the current task
(e.g., read_context("api-contracts"))
│
▼
3. Agent writes code adhering to exact invariants
│
▼
4. Architectural change? Agent mutates the markdown file in-place
```

Instead of dumping 15 KB of architectural docs into the system prompt, the agent starts every session with a tiny, auto-generated index:

```
{
  "topics": ["auth-flow", "error-handling", "database-conventions"],
  "total_files": 3
}
```

*Cost: ~100 tokens.* The model calls `read_context("auth-flow")`

**only if** the prompt touches authentication.

Vectors 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.**

Because memory is just flat `.md`

files inside the repository:

`.opencontext/api-contracts.md`

, 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.

In your `claude.json`

or Cursor MCP settings:

```
{
  "mcpServers": {
    "opencontext": {
      "command": "npx",
      "args": ["-y", "opencontext-mcp"]
    }
  }
}
```

Now, instead of re-explaining constraints, you can simply tell your agent:

"Check the database conventions in our context and scaffold the new user billing schema."

The agent checks the index, reads `.opencontext/database-conventions.md`

, adheres to your patterns, and moves on.

We don't need complex vector pipelines for single-repository agent memory.

Plain 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.

**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?**