Yes. Nexus-MCP is open source under the MIT license, for any use, including at work.

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

Your agent forgets.
Your codebase shouldn't.

Q: How do I test Nexus-MCP on my own code before I install it?

Run uvx nexus-mcp-ci eval in your project folder. It compares Nexus-MCP with Grep and Read on about 30 questions made from your code, offline and with no LLM calls, and prints a verdict: Strong fit, Likely fit or Weak fit. Measured median tokens to reach the right file, Nexus-MCP against Grep and Read: 950 against 17,998 on Chromium base/ (3,638 files), 1,301 against 24,774 on pallets/click (91 files) and 1,234 against 5,385 on the Nexus-MCP source. For real agent cost, nexus-mcp-ci eval --agent claude runs a paid A/B with your own Claude Code login after it shows the cost.

Q: 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.

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.

uvx nexus-mcp-ci eval

Test it on your repo →

Free, offline, no LLM calls: it measures Nexus-MCP against Grep and Read on your own code. Already convinced? 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: MIT. Free for any use, including at work.
Downloads: total on PyPI (pypistats)
Listed on: PyPI, Glama, GitHub

Not sure yet?

Measure it on your own code first.

One command compares Nexus-MCP with Grep and Read on questions made from your project. It is free, runs offline and calls no LLM. Your code does not leave your machine.

Run the check in your project folder

uvx nexus-mcp-ci eval

No project at hand? uvx nexus-mcp-ci eval --example runs it on the Nexus-MCP source. A public repo URL works too.
Read the verdict

"Strong fit", "Likely fit" or "Weak fit", with the tokens an agent needs to reach the right file. On Chromium's base/ (3,638 files): "Strong fit", 950 median tokens against 17,998, and the right file first in 70% of questions against 40%. On pallets/click (91 files): "Strong fit", 1,301 against 24,774, right file first 97% against 27%. On the Nexus-MCP source: 1,234 against 5,385. On a tiny project Grep and Read win, and the report says so. All results.
Adopt, measure the real cost, or share

Install it in 60 seconds. Or run nexus-mcp-ci eval --agent claude for a paid A/B with your own Claude Code login (it shows the cost and asks first). nexus-mcp-ci eval share adds your numbers to the community table, only after you say yes.

The problem

Agents write fast. They remember nothing.

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.

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.

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 type	native grep
Code that matches an idea, not a name	search
Why a decision was made last month	memory
The shape of an unfamiliar repo	map
Hotspots before a refactor	analyze

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 Read	Result
Private Python project, 460 files: turns	55 → 35
Private Python project: cost	−22%
Django, 3,000 files: turns	93 → 71
Django: cost	−3%
Correct answers: Nexus, then Grep and Read	71 · 70 of 72
Chromium base/, 3,638 files: tokens to the right file (`eval`, no LLM)	17,998 → 950
pallets/click, 91 files: tokens to the right file (`eval`, no LLM)	24,774 → 1,301
Nexus-MCP source, 59 files: tokens to the right file (`eval`, no LLM)	5,385 → 1,234

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. nexus-mcp-ci data where lists every file it stores; data clear removes them. What goes in and out.

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.

What goes in and out

Your code stays on your machine.

The server makes no network calls and has no telemetry. Two downloads come in once: the package and the embedding model (set NEXUS_OFFLINE=1 after that). Nothing goes out unless you run one of two opt-in commands, and both ask first.

nexus-mcp-ci data where lists everything stored. nexus-mcp-ci data clear removes it. Every flow and location.

Get started

Install once. Every agent gets the context.

Install and connect, with one command

uvx nexus-mcp-ci setup

Needs uv. It finds your MCP clients, shows each change, and asks before it writes. Or tell your agent: “Install Nexus-MCP from github.com/jaggernaut007/Nexus-MCP”.

One click: Add to Cursor · Add to VS Code
Or connect by hand

claude mcp add nexus-mcp -- nexus-mcp-ci
```
/plugin marketplace add jaggernaut007/Nexus-MCP
/plugin install nexus-mcp@nexus-mcp
```
The plugin registers the server and adds skills that teach the agent when to use each tool.
```
{
  "mcpServers": {
    "nexus-mcp": { "command": "nexus-mcp-ci", "args": [] }
  }
}
```
Add this to claude_desktop_config.json.
```
{
  "nexus-mcp": {
    "command": "nexus-mcp-ci",
    "transport": "stdio"
  }
}
```
Any client that speaks MCP over stdio works the same way.
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 test Nexus-MCP on my own code before I install it?

Run uvx nexus-mcp-ci eval in your project folder. It compares Nexus-MCP with Grep and Read on about 30 questions made from your code, offline and with no LLM calls, and prints a verdict: Strong fit, Likely fit or Weak fit. Measured median tokens to reach the right file, Nexus-MCP against Grep and Read: 950 against 17,998 on Chromium base/ (3,638 files), 1,301 against 24,774 on pallets/click (91 files) and 1,234 against 5,385 on the Nexus-MCP source. For real agent cost, nexus-mcp-ci eval --agent claude runs a paid A/B with your own Claude Code login after it shows the cost. The full guide.

How does Nexus-MCP compare with Serena and claude-context?

Serena finds code through language servers and can edit code. claude-context runs hybrid search over a vector database such as Milvus or Zilliz Cloud with an embedding provider. Nexus-MCP is read only and fully local: hybrid vector and BM25 search in a local LanceDB index with a local embedding model, a static call graph for six languages, and project memory. Measure it on your own repository with nexus-mcp-ci eval instead of relying on any comparison.

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. The source is public on GitHub under the MIT license. You can use it for any purpose, including at work.

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, has no telemetry and needs no API keys. The embedding model downloads once, at first use; set NEXUS_OFFLINE=1 after that. The index lives in .nexus/ in your project: nexus-mcp-ci data where lists every stored file and nexus-mcp-ci data clear removes them. Only the opt-in eval --agent (through your own Claude or Codex CLI) and eval share (numbers only) send anything, and both ask first. Every flow and storage location.

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.

Start with your own numbers: uvx nexus-mcp-ci eval. Then star the repo, share your result, or send a pull request. Feedback from real projects shapes what ships next.

Evaluate on your repo Star on GitHub Open an issue View on PyPI

Your agent forgets.Your codebase shouldn't.

What is Nexus-MCP?

Measure it on your own code first.

Run the check in your project folder

Read the verdict

Adopt, measure the real cost, or share

Agents write fast. They remember nothing.

Every session starts from zero

The docs drift from the code

Features hide across files

Three kinds of context your agent is missing.

Project memory that outlives the session

Architecture docs that update themselves

Understand a feature without a file tour

Grep for names. Nexus for everything grep cannot see.

Fewer turns for the same answers.

Eight tools. Each one earns its call.

Private by design

Light on your laptop

Any MCP client

Safe defaults

Your code stays on your machine.

Install once. Every agent gets the context.

Install and connect, with one command

Or connect by hand

Ask your agent a question

Before you install.

Give your agent a memory.

Your agent forgets.
Your codebase shouldn't.