Nexus-MCP GitHub

Local MCP server · v2.1 · Python 3.10–3.12

Your agent forgets.
Your codebase shouldn't.

Nexus-MCP gives AI coding agents the context they lose between sessions. It keeps project decisions in a searchable memory, draws a live map of your architecture, and returns the code your agent asks for in fewer calls. It runs on your machine. It needs no API keys.

pip install nexus-mcp-ci
Set it up in 60 seconds →
  • 0 API keys
  • ~90 MB RAM idle
  • 25+ languages
  • 8 focused tools

agent session · day 14

# New session. The agent recalls last week's decision.
memory(action="search", query="retry policy for payments")
→ decision · 9 days ago · tags: file:billing/retry.py
  "Use exponential backoff, max 5 tries. Never retry
   card_declined. Agreed with @ops after the March outage."

# Where does that live? Ask by concept, not by name.
search("how failed charges are retried")
→ billing/retry.py:42    schedule_retry()      0.94
→ billing/webhooks.py:18 on_charge_failed()    0.88

# Read it before you touch it. No file tour.
find_symbol("schedule_retry, RetryJob")
→ billing/retry.py:42-61  def schedule_retry(charge, attempt)
  code: whole function · callers: on_charge_failed()
→ billing/jobs.py:8       class RetryJob · outline, 4 methods
Illustrative output. Real results depend on your code.

In one paragraph

What is Nexus-MCP?

Nexus-MCP is a local Model Context Protocol (MCP) server for AI coding agents. It adds three things an agent lacks by default: persistent project memory across sessions, a live map of your codebase, and the code of any function or class, with its callers, in one call. It works with Claude Code, Claude Desktop, Cursor, Windsurf, Cline, Continue and Goose.

Install
pip install nexus-mcp-ci
Runs
Locally. No API keys.
Transport
MCP over stdio
Languages
25+ (tree-sitter)
License
PolyForm Noncommercial 1.0.0
Listed on
PyPI, Glama, GitHub

The problem

Agents write fast. They remember nothing.

01

Every session starts from zero

Why did the team pick this queue? Which test is flaky? The agent does not know. You explain it again, every day.

02

The docs drift from the code

Architecture notes go stale after one refactor. The agent reads the old note and makes a confident, wrong change.

03

Features hide across files

"How does checkout work?" has no single file to open. Grep needs the exact name, and you do not know it yet.

What Nexus-MCP adds

Three kinds of context your agent is missing.

Context · memory

Project memory that outlives the session

The agent stores decisions, preferences, status and notes as it works. The next session recalls them by meaning, not by file name.

  • Store, search and delete with one tool and three actions
  • Tag a memory to a file or a symbol, then filter by tag
  • Kept with the project index, in the .nexus folder
  • One local store. Any MCP client can read it, so your context stays when you change agents.
memory(
  action="store",
  content="Auth tokens live 15 min. Refresh
           tokens rotate on every use.",
  tags="decision,file:auth/tokens.py",
)
→ stored · id m_7f3a
Documentation · map · analyze

Architecture docs that update themselves

Ask for a map and get the layers, entry points, key classes and hub symbols of the code as it is now. A file watcher re-indexes after each change, so the map does not go stale.

  • Summary, architecture or full detail, in one call
  • Complexity, code smells and dependency metrics per path
  • Incremental re-index on file change. Branch switches too.
map(detail="architecture")
→ layers
    api/        → 14 files · entry: main.py
    services/   → 22 files · hub: OrderService
    storage/    →  9 files
  entry points  main.py, worker.py, cli.py
  languages     python 81% · typescript 19%

analyze("services/")
→ 2 functions over complexity 15
  1 long parameter list · OrderService.create
Code · search · find_symbol

Understand a feature without a file tour

Describe the behaviour in your own words. Hybrid search combines meaning and keywords to find the right functions, and its top results carry their whole code. Then find_symbol gives the code of several names in one call, with their callers and callees.

  • Vector + BM25 search, merged with Reciprocal Rank Fusion
  • Exact names in a query come first; source files before tests
  • A long class comes back as an outline; ask for Class.method
search("where do we stop duplicate orders")
→ orders/idempotency.py:12  check_key()   0.93
→ api/middleware.py:57      dedupe()      0.86

find_symbol("check_key, dedupe")
→ code, file, line range,
  direct callers and callees of each

Works with your agent, not against it

Grep for names. Nexus for everything grep cannot see.

Your agent already has fast, exact file search. Keep it. Nexus-MCP does not replace it. Use native search for a name you can type. Call Nexus when the answer needs meaning, history or structure.

When to use native search and when to use Nexus-MCP
You need…Use
An exact name or string you can typenative grep
Code that matches an idea, not a namesearch
Why a decision was made last monthmemory
The shape of an unfamiliar repomap
Hotspots before a refactoranalyze

Measured, not estimated

Fewer turns for the same answers.

Each turn of an agent reads the whole conversation again, so a saved turn is a saved cost. We ran 12 questions per project with Claude Sonnet, 3 runs each, against an agent with only Grep and Read. The saving is large on code the model does not know and small on code it knows. Run the benchmark on your own project before you rely on it.

Live benchmark of Nexus-MCP against Grep and Read, version 2.1
Nexus-MCP against Grep and ReadResult
Private 460-file Python project: turns55 → 35
Private project: cost−22%
Django, 3,000 files: turns93 → 71
Django: cost−3%
Correct answers: Nexus, then Grep and Read71 · 70 of 72

The tool surface

Eight tools. Each one earns its call.

memory

Store, search and delete project knowledge across sessions.

map

Project summary and architecture: layers, entry points, hubs.

analyze

Complexity, code smells and dependency metrics for a path.

search

Hybrid semantic + keyword search. Top results carry their code.

find_symbol

The code of one or more names, with callers and callees.

graph

Callers, callees, change impact and every text reference.

index

Incremental, multi-folder indexing with an auto-watch.

status

Index counts, memory use and a staleness flag.

Private by design

Embeddings run locally. Your code never leaves the machine. It works offline and in air-gapped setups.

Light on your laptop

Disk-backed vectors and a lazy-loaded model keep it near 90 MB idle. With the embedding model loaded it uses about 460 MB.

Any MCP client

Standard stdio transport. Config by NEXUS_* environment variables, not vendor files.

Safe defaults

Input validation, read-only permission mode, audit logs with redaction, and optional rate limits.

Get started

Install once. Every agent gets the context.

  1. Install the package

    pip install nexus-mcp-ci

  2. Connect your agent

    claude mcp add nexus-mcp -- nexus-mcp-ci

  3. Ask your agent a question

    The agent calls index on first use. After that, it recalls memory, maps the repo and finds code for you. A file watcher keeps the index current.

Questions

Before you install.

What is Nexus-MCP?

Nexus-MCP is a local Model Context Protocol (MCP) server for AI coding agents. It gives an agent persistent project memory, a live map of the codebase, hybrid semantic and keyword code search, and the code of any symbol in one call. It runs on your machine and needs no API keys.

How do I give Claude Code persistent memory across sessions?

Install Nexus-MCP with pip install nexus-mcp-ci, then register it with claude mcp add nexus-mcp -- nexus-mcp-ci. The agent can then store decisions, notes and preferences with the memory tool and recall them by meaning in later sessions. The memory store is local and any MCP client can read it.

Does Nexus-MCP lower token use?

On the projects we measured, yes, through fewer turns. In 12 live questions per project with Claude Sonnet, Nexus-MCP cut turns from 55 to 35 on a private 460-file project and from 93 to 71 on django. Cost fell by 22% and 3%. Cost varies by about 20% over 3 runs, so the django result is about equal. docs/EVALS.md has every number.

Is Nexus-MCP free?

Yes, for personal, research, education and other noncommercial use. The source is public on GitHub under the PolyForm Noncommercial 1.0.0 license. Commercial use needs a separate license from the maintainer.

Does my code leave my machine?

No. Parsing, embeddings, the vector store and the memory store all run locally. Nexus-MCP sends no code to any service and needs no API keys. The embedding model downloads once, at first use.

Which AI coding agents and MCP clients does it work with?

Any MCP client that supports the stdio transport. That includes Claude Code, Claude Desktop, Cursor, Windsurf, Cline, Continue and Goose.

Which programming languages does Nexus-MCP support?

Symbol extraction and search cover more than 25 languages through tree-sitter. Structural data for the map and graph tools is available for Python, JavaScript, TypeScript, Go, Java and Rust.

Will the code index go stale?

A debounced file watcher re-indexes changed files a few seconds after you save. The status and search tools also run a throttled staleness check and flag old results. Branch switches are detected by file modification time.

What is not finished yet?

The graph tool uses static call edges, so it cannot see dynamic dispatch or callbacks and its results are a lower bound. The README lists all known limits.

Give your agent a memory.

Star the repo, open an issue, or send a pull request. Feedback from real projects shapes what ships next.

Star on GitHub Open an issue View on PyPI