code-meridian
Driftya/code-meridian
Local graph memory for AI coding agents, giving MCP-compatible tools precise codebase context before they edit.
Instalação
npx convez-ai Driftya/code-meridian1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
CodeMeridian
CodeMeridian is a local graph memory layer for AI coding agents.
It indexes your codebase into Neo4j and exposes that structure through MCP, so AI coding tools can ask precise questions before editing instead of guessing from open files. It works with MCP-compatible clients such as GitHub Copilot, Claude Code, Continue.dev, Codex-style agents, Cline, and local agent workflows.
It is built to be the deterministic context layer for large codebases: callers, dependencies, tests, documentation, hotspots, dead code, diagnostics, and cross-project relationships stay available across sessions.
This is especially useful for local or smaller coding models, where every token matters. CodeMeridian does not try to replace the model. It makes the model’s job smaller by giving it the smallest useful slice of architecture before it writes code.
Core usage requires no LLM API key. Optional semantic features can use local Ollama or a cloud embedding provider. 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 |
|---|---|
| The assistant loads files ad hoc as it searches for context | The assistant 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 | The agent gets the smallest useful architecture slice |
| Small local models struggle with broad repository context | Graph-backed context makes the task smaller |
| 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_contextestimates 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.
Built for agent-first workflows
AI coding agents are powerful, but they often work from incomplete or temporary context. They may search files repeatedly, miss hidden callers, forget previous discoveries, or fill their context window with noisy whole-file dumps.
CodeMeridian gives those agents a persistent graph-backed map of the repository. Instead of asking the model to rediscover the codebase every session, the agent can query CodeMeridian for the specific architecture slice it needs.
Typical workflow:
- Start CodeMeridian locally.
- Index your repository.
- Connect an MCP-compatible coding agent.
- Ask the agent to build a minimal context pack before editing.
- Let the agent use impact, freshness, documentation, and test-coverage checks while it works.
Example prompt:
Use CodeMeridian to build a minimal context pack for the authentication flow before changing login behavior.
Why this helps smaller local models
Small local coding models are most useful when the context is precise. CodeMeridian helps by turning a repository into a graph-backed memory layer, so agents can retrieve the smallest useful context instead of scanning the whole codebase.
This is useful for 7B-class models, low-memory machines, and local-first workflows where context size, privacy, and repeatable code understanding matter.
Without CodeMeridian, the model may need to infer architecture from file names and ad hoc searches. With CodeMeridian, the agent can ask targeted questions:
What calls this method?
Which tests cover this service?
Which frontend components use this endpoint?
What docs mention this symbol?
Is the graph fresh enough to trust?
What is the smallest context needed for this edit?
CodeMeridian does not make a small model magically perfect. It reduces the amount of guessing the model has to do.
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
- Usage
- 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.