Why Your AI Coding Assistant Doesn't Actually Know Your Codebase

I kept watching my AI assistant make the same mistakes

Here's something that bugged me for months.

Every time I started a new coding session — whether in Cursor, a custom agent pipeline, or just Claude with a big paste — the AI had zero memory of the codebase I'd been living in. It didn't know that NotificationService implements INotificationService. It didn't know which HTTP clients hit which external APIs. It had no idea about the architectural patterns my team agreed on last quarter, or how flows work in our Flutter app, or which services get injected where.

So it guessed. Sometimes it asked me to paste in context. Sometimes it read a handful of files and extrapolated from there. And honestly? It was right often enough to be useful. But it was also confidently wrong often enough to be dangerous — generating code that looked correct, passed a cursory review, and then broke something three layers deep.

This isn't me complaining that AI is bad. The models are incredible. The problem is structural: AI coding tools are stateless. Codebases are not.

The tools we have don't solve this

I tried everything. None of it worked the way I needed.

Grep and code search find text. That's it. They can't tell you that the class you're looking for gets injected into three different services, or that the endpoint you're about to modify shares a DTO with two other routes you've never touched.

Documentation goes stale within weeks. Even our well-maintained wiki described services by names we'd renamed months ago. Docs tell you what someone intended the code to do. They rarely reflect what it actually does today.

IDE indexers know syntax, not architecture. "Go to definition" is great. But it can't tell you why a class exists, what role it plays in the overall data flow, or what would break downstream if you changed its interface.

Agentic context scanning (the thing most AI tools do per-session) is expensive and lossy. They burn through tokens rebuilding the same understanding every single time. And because they start fresh, they miss the cross-file relationships that only become visible when you've resolved the full dependency graph.

I kept coming back to the same realization: there's no persistent layer that actually understands a codebase and lets you query that understanding.

So we built one.

What RCE actually is

The Repository Cognition Engine is something we've been building at Deep Sky Labs to scratch our own itch. It takes a raw codebase and transforms it into a persistent, queryable index — one that can answer architectural questions with specific, verifiable answers instead of plausible-sounding guesses.

It's not a doc generator. It's not a fancy code search. It's not a linter.

Think of it more like having a senior engineer on the team who's read every file, traced every dependency, and can answer "what would break if I changed this?" in seconds. Except it doesn't go on vacation and it doesn't forget things between standups.

We've published the package so you can try it yourself:

GitHub (Issues & Feedback): Deep-SkyLabs/Repository-Cognition-Engine-public
PyPI: repository-cognition-engine

The key insight: extract facts first, then reason

Here's where most AI code tools get it backwards.

They take your raw source files, shove them into an LLM context window, and ask the model to figure out what's going on. The LLM is great at pattern completion, so it produces answers that sound right. But those answers aren't grounded in your actual codebase. They're educated guesses based on what codebases generally look like.

We flipped that. RCE deterministically extracts real facts — actual class names, actual method signatures, actual dependency registrations, actual API routes — before any LLM touches anything. The model's job is never to discover what exists. It only reasons over facts that extraction has already confirmed are real.

┌─────────────────┐       ┌──────────────────────────┐       ┌────────────────┐
│  Raw Codebase   │ ───>  │  AST & Git               │ ───>  │ Persistent     │
│  (Files/Git)    │       │  Deterministic Extraction│       │ .rce/ Index    │
└─────────────────┘       └──────────────────────────┘       └────────────────┘
                                                                     │
                                                                     ▼
┌─────────────────┐       ┌──────────────────────────┐       ┌────────────────┐
│ Grounded Answer │ <───  │ LLM Reasoning            │ <───  │ Query + Target │
│ (No Hallucinations)     │ (Claude/Gemini/API)      │       │ Facts Context  │
└─────────────────┘       └──────────────────────────┘       └────────────────┘

In practice, this means:

Language-specific AST extraction parses every file in your repo — pulling out symbols, functions, classes, imports, exports, and dependency patterns. Separately, a Git Coupling Matrix computes which files change together, how often, and by whom.
Framework detection figures out what kind of project you're working with — the language mix, entrypoints, architectural layers — and builds a structural model automatically.
Everything persists to disk in a .rce/ directory (index.json, symbols.json, cochange.json, etc). When files change, only the diffs get re-indexed. You never rebuild from scratch.
When you ask a question, RCE pulls the exact relevant context from the index and hands it to the LLM. No hallucinated class names. No phantom file paths. No invented relationships.

That last point is the one that matters most. The difference between "the LLM guessed this class exists" and "extraction confirmed this class exists at line 47 of this file" is the difference between useful and dangerous.

Try it — it takes about 30 seconds

Install from PyPI:

pip install repository-cognition-engine

Then point it at any repo:

Index your codebase

rce analyze .

Want to run completely offline, no API keys needed? Just add --no-llm:

rce analyze . --no-llm

Ask it questions

rce ask "How does authentication work in this project?"

Check what breaks before you edit

rce impact path/to/service.py

This shows you direct dependencies, dependents, co-change partners from Git history, and a regression risk assessment — before you touch a single line.

Generate onboarding docs from the actual code

rce docs --output docs/rce

This creates ARCHITECTURE.md, ONBOARDING.md, and agent-specific guidelines (CLAUDE.md / ANTIGRAVITY.md) — all derived from what the code actually does, not what someone wrote in a wiki six months ago.

It plugs directly into your AI agent

This is the part I'm most excited about. RCE ships with a built-in MCP server (rce-mcp) that lets AI assistants query your codebase intelligence natively — no copy-pasting, no manual context loading.

If you use Claude Desktop, add this to your config (%APPDATA%\Claude\claude_desktop_config.json on Windows, ~/.config/claude/claude_desktop_config.json on Mac/Linux):

{
  "mcpServers": {
    "rce": {
      "command": "rce-mcp",
      "args": []
    }
  }
}

For Cursor, add it in your MCP settings or .cursor/mcp.json — command is just rce-mcp.

Once connected, your AI assistant gets access to tools like:

trace_call_chain — follow execution flow through methods and services
get_implementations — find every class implementing a given interface
get_api_surface — pull all endpoints, HTTP methods, and auth schemas
get_feature_context — get a curated context pack for a specific task
find_similar — discover files with shared structural patterns or Git co-change history

The difference is night and day. Instead of the agent burning 10k tokens reading files and still missing half the picture, it gets exactly the structural context it needs in one call.

It speaks six languages (and counting)

Real teams don't write everything in one language. We built RCE with that assumption from day one.

It currently supports C#, Dart/Flutter, TypeScript, Python, Java, and Go — and not just at a superficial level. Each language gets its own extraction logic that understands the idioms developers actually use: .NET DI registration patterns, Flutter flow architecture, Python import resolution, TypeScript decorators, Spring annotations, Go interface satisfaction.

If you're running a polyglot monorepo, RCE treats it like one. No flattening everything into a generic symbol list.

What we're actually shipping: accuracy you can act on

Look — any LLM can give you an answer about code. That's the easy part. The hard part is giving you an answer that's accurate enough to act on without double-checking everything.

That's the bar we set for RCE. Every answer cites specific file paths and symbol names. If it's not sure about something, it says so instead of making something up. No hallucinated class names, no phantom files, no "this might work" when it actually won't.

That reliability is the whole point.

GitHub: https://github.com/Deep-SkyLabs/Repository-Cognition-Engine-public
PyPI: https://pypi.org/project/repository-cognition-engine

Give it a spin on your messiest repo. That's where it shines.