CodeMeridian: Giving AI Coding Agents a Project Map Before They Edit

AI coding agents feel sharp when a project is small.

They can scan a few files, understand the shape, and make useful changes. In that phase, the project still fits inside the agent’s short-term memory. The architecture is obvious. The dangerous files are nearby. The blast radius is small.

But something changes when a project reaches MVP size.

The agent still sounds confident, but it starts guessing.

It finds a nearby file and assumes it is the right one.

It trusts stale documentation.

It misses hidden callers.

It forgets architecture boundaries.

It edits something that was not really part of the task.

I kept running into that problem while building larger projects.

Source-level guardrails help. A CONTRIBUTING.md, AGENTS.md, or project instruction file can tell the agent how to behave.

But those are still instructions.

They are not facts.

That is where the idea for CodeMeridian came from.

What CodeMeridian is

CodeMeridian is a local code knowledge graph for AI coding tools.

It indexes a codebase into Neo4j and exposes that graph through MCP, so tools like GitHub Copilot, Claude Code, Codex-style agents, or other MCP-compatible clients can ask better questions before editing.

The basic idea is:

The assistant is the AI.

CodeMeridian is the project map.

It does not replace the coding assistant. It gives the assistant a structured way to ask about the codebase.

Examples:

What calls this method?

What tests cover this area?

What files are likely in scope for this feature?

Is the graph stale before I trust it?

How is this frontend component connected to backend code?

Why a graph?

Code is already a graph.

Methods call methods.

Classes implement interfaces.

Tests cover production paths.

Frontend components call API clients.

API handlers touch services.

Services use repositories.

Docs mention symbols.

Projects depend on other projects.

A normal file search can find text.

A graph can answer relationship questions.

That matters because many AI coding mistakes are relationship mistakes.

The agent edits a method but misses its callers.

It changes an interface without checking implementations.

It deletes code that looks unused but is actually an entry point.

It trusts documentation that no longer matches the code.

CodeMeridian tries to make those relationships visible before the edit happens.

A red line before the agent touches the code.

What it currently indexes

CodeMeridian currently supports:

• C# through a Roslyn-based indexer


• TypeScript / TSX through a frontend indexer


• README and documentation files


• diagnostics


• optional embeddings for semantic similarity

The graph is stored locally in Neo4j.

There is no CodeMeridian cloud service.

No LLM API key is required for CodeMeridian itself. The AI assistant you use may have its own requirements, but the knowledge graph belongs to you.

What the MCP tools can do

The current toolset is focused on helping an agent understand impact, context, and risk.

Some examples:

find_impact

Finds callers and transitive dependents before changing something.

build_minimal_context

Builds a bounded context pack for a target node, including callers, callees, likely files, tests, coverage gaps, token estimate, and model guidance.

find_implementation_surface

Ranks the files, classes, and methods most likely to be relevant for a feature goal.

check_graph_freshness

Reports whether the indexed graph looks trustworthy enough for exact implementation work.

find_graph_drift

Checks if the graph may be stale and whether re-indexing is recommended.

find_stale_knowledge

Looks for stale docs, unresolved mentions, orphaned concepts, and code references that no longer resolve.

The goal is not to flood the agent with more text.

The goal is to return the smallest useful architecture slice.

The workflow I want

The ideal workflow looks something like this:

Use CodeMeridian before editing.

Goal:

Add unread reply notifications.

Steps:

1. Find the likely implementation surface.


2. Resolve exact symbols where possible.


3. Check graph freshness.


4. Build a minimal context pack.


5. Identify related tests.


6. Make the smallest safe change.


7. Verify with tests.

That is very different from:

Search around and hope the right files are nearby.

The first workflow gives the agent a map.

The second gives it a flashlight and a haunted repo.

Why local-first matters

For this kind of tool, I wanted the graph to be local.

The code structure, documentation, diagnostics, and remembered project knowledge should not need to live in someone else’s hosted service.

Neo4j runs locally.

The MCP server runs locally.

The indexer runs locally.

If you use a hosted assistant, that assistant still has its own data handling rules. But CodeMeridian itself is not a cloud knowledge store.

What this is not

CodeMeridian is not an AI model.

It is not a replacement for tests.

It is not a replacement for code review.

It is not magic.

It is a project memory layer for AI-assisted coding.

The agent can still make mistakes. But with a graph, at least it can ask better questions first.

Where I want to take it next

The current version is early but usable.

The next improvements I am thinking about are more workflow-focused:

• better usage prompts


• troubleshooting docs


• a small UI for reviewing frontend/backend link suggestions


• background graph enrichment


• test shield summaries


• change-session memory


• better Docker image publishing and install flow

One feature I am especially interested in is a manual relationship workbench:

The indexer could suggest possible frontend-to-backend links, such as:

CreateNoteForm.tsx -> POST /api/notes -> NoteEndpoints.CreateAsync

Then a developer could confirm or reject those links in a small UI.

That would turn CodeMeridian from a passive index into a curated system map.

Repo

The project is here: