CodeMeridian

CodeMeridian is a persistent code knowledge graph for AI coding tools. It indexes your codebase into Neo4j and exposes that structure through MCP, so GitHub Copilot, Codex, Claude Code, and other MCP-compatible clients can ask precise questions before editing instead of guessing from open files.

It is built to be the deterministic context layer for large codebases: callers, dependencies, tests, documentation, hotspots, dead code, and cross-project relationships stay available across sessions.

No LLM API key required. The assistant is the AI; CodeMeridian is the knowledge engine.

Why CodeMeridian?

Copilot can still read files beyond what is already open, but it has to spend context to discover them and the relationships do not persist. CodeMeridian makes that discovery explicit, cheaper, and reusable.

The graph is yours. CodeMeridian stores indexed code structure, documentation, diagnostics, and remembered project knowledge in your Neo4j instance. Nothing is sent to a CodeMeridian cloud service. If you use Copilot, Codex, Claude Code, or another hosted assistant, that assistant still has its own data handling rules, but the CodeMeridian knowledge graph itself stays under your control.

Without CodeMeridian	With CodeMeridian
Copilot loads files ad hoc as it searches for context	Copilot queries a graph of your entire codebase
Context disappears between sessions	Knowledge persists locally in Neo4j
"What calls this method?" requires manual searching	find_impact answers from the call graph
Refactors can miss hidden callers	Blast radius is known before edits
Dead code and test gaps stay invisible	find_unreferenced and find_coverage_gaps surface them
Large context windows get filled with noise	Copilot gets the smallest useful architecture slice
Assistants guess which model/context size is enough	Context packs include token estimates and model guidance
Stale indexes quietly mislead agents	Freshness and drift checks say when to re-index
Docs and decisions live outside the code graph	Knowledge, docs, diagnostics, and code links can be queried together

What this gives you in practice:

• Local ownership: the graph and knowledge store run in your Neo4j, not a hosted CodeMeridian service.
• Persistent memory: architecture, docs, diagnostics, external concepts, and agent notes survive editor restarts.
• Lower context waste: tools return callers, callees, tests, likely files, and small snippets instead of whole-file dumps.
• Safer edits: impact, downstream dependencies, diagnostics, drift, and missing tests are visible before implementation.
• Model-aware context: build_minimal_context estimates token cost and suggests when a small model is enough.
• Explainable results: exact, heuristic, stale, and file-only matches are labeled so the assistant can say what it trusted.

What It Indexes

CodeMeridian currently supports:

• C# via a Roslyn indexer
• TypeScript / TSX via a ts-morph indexer
• README and documentation files
• Optional vector embeddings for semantic code similarity (find duplicate patterns, refactoring opportunities)

The indexer is designed as a language-agnostic pipeline: future language indexers can write into the same graph model and be queried through the same MCP tools. Embeddings are opt-in (disabled by default) and are now generated by the CodeMeridian backend, which can use local Ollama (free) or OpenAI (paid).

Quick Start

Prerequisites:

• Docker Desktop
• .NET 10 SDK
• GitHub Copilot in VS Code
• Node.js 18+ when indexing TypeScript / TSX

Install the CLI:

dotnet tool install -g CodeMeridian.Indexer

Start CodeMeridian:

codemeridian serve

Index this repository:

codemeridian index . --clear

If you are running from a source checkout before installing the global tool:

Copy-Item .env.sample .env
docker compose up -d
dotnet run --project tools/Indexer -- . --clear

To create a local project config and MCP client config, run:

codemeridian init .

Open this folder in VS Code or any MCP-capable client. The MCP server is registered through .vscode/mcp.json, and MCP-compatible clients can call CodeMeridian tools while you chat.

Common Questions

Ask Copilot things like:

Use CodeMeridian to give me an architectural overview.

Before changing OrderService.PlaceOrderAsync, what calls it?

Which methods have no test coverage?

Build a minimal context pack before I change OrderService.PlaceOrderAsync.

How is this TypeScript component connected to the backend?

Usage

See usage.md for copy-paste prompts that help AI coding assistants use CodeMeridian safely before editing.

Core Tools

Tool	What it does
query_codebase	Natural-language search over code structure
get_architectural_overview	Project map by namespace/module
get_context_for_editing	Compact callers/callees/interfaces context for a node
build_minimal_context	Bounded context pack with callers, callees, impact, tests, gaps, likely files, token estimate, and model guidance
find_impact	Backward blast-radius analysis
find_connection	Shortest path between two code elements
find_unreferenced	Dead-code candidates
find_coverage_gaps	Production code not called by tests
find_similar_nodes	Find duplicate code patterns (requires embeddings enabled)
find_duplicate_candidates	Review likely duplicate methods/classes with refactor-risk signals
search_documentation	Search indexed README/ADR/documentation content
find_implementation_surface	Rank likely files and symbols to edit for a feature goal
check_graph_freshness	Report graph confidence from indexed file, line, and timestamp metadata
find_graph_drift	Detect stale graph data before relying on exact implementation targets
find_stale_knowledge	Detect stale docs, weak mentions, orphaned external concepts, and orphaned code references
resolve_exact_symbol	Resolve symbol/file/line hints to canonical node IDs before editing
clear_project_knowledge	Clear one project's indexed graph and docs before rebuilding
clear_code_graph	Clear all indexed code graph nodes while preserving docs

Documentation

• Installation
• How CodeMeridian works
• Indexing projects
• Feature reference
• Code embeddings and semantic search
• Publishing the indexer tool
• Ubuntu headless deployment
• Contributor and agent guide

Project Layout

src/
  Core/             Domain models
  Application/      Query services and orchestration
  Infrastructure/   Neo4j graph and knowledge storage
  McpServer/        MCP server and REST ingestion API
  Sdk/              Client library for ingestion
tools/
  Indexer/          Unified indexer CLI
  RoslynIndexer/    C# Roslyn indexer
  TsIndexer/        TypeScript / TSX indexer
docs/
  features.md
  how-it-works.md
  installation.md
  indexing.md
  publishing.md

Status

CodeMeridian is early but usable. It already indexes C# and TypeScript/TSX projects, persists the graph in Neo4j, and exposes MCP tools for Copilot, Codex, and other compatible clients. The roadmap is tracked in TODO.md.