Local MCP server · v2 · Python 3.10–3.12

Your agent forgets.
Your codebase shouldn't.

Q: 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 symbol explanations. It runs on your machine and needs no API keys.

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-ci -- 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.

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

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

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

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

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

Q: What is not finished yet?

Call edges are not extracted yet, so the graph tool returns empty caller and callee lists today. Memory, map, analyze, search and explain work now. The README lists all known limits.

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 explains any feature in plain terms. It runs on your machine. It needs no API keys.

pip install nexus-mcp-ci

Set it up in 60 seconds →

0 API keys
<350 MB RAM target
25+ languages
10 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

# Explain it before you touch it.
explain("schedule_retry", verbosity="summary")
→ def schedule_retry(charge, attempt) -> RetryJob
  "Queue the next attempt with jittered backoff."
  related: retry_job(), on_charge_failed()
  complexity 6 · no smells

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 plain explanations of any function or class. It works with Claude Code, Claude Desktop, Cursor, Windsurf, Cline, Continue and Goose.

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

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.

Six memory types: note, decision, conversation, status, preference, doc
Expiry that you control, from one session to permanent
Tag a memory to a file or a symbol, then filter by tag
One local store. Any MCP client can read it, so your context stays when you change agents.

memory(
  action="store",
  memory_type="decision",
  content="Auth tokens live 15 min. Refresh
           tokens rotate on every use.",
  tags="file:auth/tokens.py,security",
  ttl="permanent",
)
→ 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

Explanation · search · explain

Understand a feature without a file tour

Describe the behaviour in your own words. Hybrid search combines meaning, keywords and code structure to find the right functions. Then explain gives the definition, docstring and quality in a token budget you pick.

Vector + BM25 search, merged with Reciprocal Rank Fusion
Optional local re-ranker for sharper results
Three verbosity levels: summary, detailed, full

search("where do we stop duplicate orders")
→ orders/idempotency.py:12  check_key()   0.93
→ api/middleware.py:57      dedupe()      0.86

explain("check_key", verbosity="detailed")
→ signature, docstring, line range,
  related chunks, complexity metrics

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

The tool surface

Ten 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, with live-grep fallback.

explain

One symbol, explained at the verbosity you ask for.

find_symbol

Exact or fuzzy lookup of a function, class or method.

graph

Containment and import structure. Call edges are in progress.

preview

index

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

status

Index health, counts, memory use and a staleness flag.

health

Liveness probe: uptime and which engines are ready.

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 the RAM target under 350 MB, next to your local LLM.

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.

Install the package

pip install nexus-mcp-ci
Connect your agent

claude mcp add nexus-mcp-ci -- 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-ci": { "command": "nexus-mcp-ci", "args": [] }
  }
}
```
Add this to claude_desktop_config.json.
```
{
  "nexus-mcp-ci": {
    "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 explains 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 symbol explanations. 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-ci -- 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.

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?

Call edges are not extracted yet, so the graph tool returns empty caller and callee lists today. Memory, map, analyze, search and explain work now. 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

Your agent forgets.Your codebase shouldn't.

What is Nexus-MCP?

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.

Ten tools. Each one earns its call.

Private by design

Light on your laptop

Any MCP client

Safe defaults

Install once. Every agent gets the context.

Install the package

Connect your agent

Ask your agent a question

Before you install.

Give your agent a memory.

Your agent forgets.
Your codebase shouldn't.