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

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