Nucleus
Shared local decision log and persistent memory for Claude Code, Cursor and Codex
- Pricing
- Open source
- Platforms
- CLI, self-hosted, Linux
- Runs
- Locally or Remotely
- Version
- 1.17.1
- Listing updated
- 3 days ago
About Nucleus
Nucleus is an open-source MCP server for knowledge and memory. It can run locally on your machine or as a hosted remote server.
Everything lives in a .brain folder inside your repo, as plain JSON and markdown with no embeddings, so each AI tool starts a session already knowing past decisions, policies and plans. It is MIT licensed and installs from PyPI with nucleus init, which seeds the folder, writes a project .mcp.json and offers to configure the clients it finds. The README says hosted access is currently unavailable, so use the local install.
The README organises it around three loops. GROUND verifies AI-written code in five tiers: diff, syntax, imports, tests and runtime. ALIGN records your correction as a verdict against a prior decision, which becomes a training pair and an event. COMPOUND measures the gap between intent and reality so recurring patterns can become strategy. Tool responses carry a frontier health line.
The README counts 30 tools across 16 facades exposing 210 actions, plus 19 brain:// resources and 8 prompts. A second tool, nucleus-rabbithole, tracks depth and context-switching for developers who lose focus, backed by local SQLite.
Install
Run in a terminal
claude mcp add --transport http nucleus https://relay.nucleusos.dev/mcpAdd to Settings → Connectors → Add custom connector
https://relay.nucleusos.dev/mcpAdd to ~/.cursor/mcp.json
{
"mcpServers": {
"nucleus": {
"url": "https://relay.nucleusos.dev/mcp"
}
}
}Add to .vscode/mcp.json
{
"servers": {
"nucleus": {
"type": "http",
"url": "https://relay.nucleusos.dev/mcp"
}
}
}Add to ~/.codeium/windsurf/mcp_config.json
{
"mcpServers": {
"nucleus": {
"serverUrl": "https://relay.nucleusos.dev/mcp"
}
}
}Add to your client's MCP settings (most use this shape)
{
"mcpServers": {
"nucleus": {
"type": "http",
"url": "https://relay.nucleusos.dev/mcp"
}
}
}Configuration
NUCLEUS_BRAIN_PATHPath to .brain/ directory (defaults to .brain in current directory)
What it does
- Portable .brain folder
- Keeps decisions, policies and plans in plain files in your repo.
- Cross-tool memory
- One MCP server serves Claude Code, Cursor and Codex.
- Execution verification
- Checks AI output through diff, syntax, imports, tests and runtime.
- One-call corrections
- Records a verdict, delta, training pair and event together.
- Rabbit-hole tracker
- Includes a depth stack and context-switch detector in local SQLite.
- Guided setup
- nucleus init configures installed AI clients.
Good for
- Stop re-explaining project decisions at each session start
- Share the same context across Cursor and Claude Code
- Verify that AI-written code actually imports and passes tests
- Record corrections as training pairs
- Track context switches during deep work
Pricing
Open source
MIT licensed; free local install
Prices change. Check nucleusos.dev before you buy.
Nucleus FAQ
Where is data stored?
In a .brain folder in your repo as JSON and markdown files.
Is there a hosted version?
The README says hosted access is not currently available.
What licence is it?
MIT.
How do I install it?
pip install nucleus-mcp, then nucleus init.
Is Nucleus free?
Yes. Nucleus is open source, so you can use and self-host it for free.
How do I add Nucleus to Claude Code?
Run this command in your terminal: claude mcp add --transport http nucleus https://relay.nucleusos.dev/mcp
What are the best alternatives to Nucleus?
The closest alternatives to Nucleus are REA, Codebase Memory, GitHub, Serena MCP: the IDE for your agent and XERJ.
Alternatives to Nucleus

REA
MCP serverCLI and MCP server that lets coding agents reverse engineer apps and binaries
Runs locally- Open source
- 464K GitHub stars
- Developer tools

Codebase Memory
MCP serverLocal MCP server that builds a code knowledge graph for AI coding agents
Runs locally- Open source
- 48.7K GitHub stars
- Knowledge and memory

GitHub
MCP serverOfficial MCP server connecting AI assistants to GitHub repos, issues and workflows
Not checked yet- Remote
- Open source
- 34.5K GitHub stars
- Developer tools

Serena MCP: the IDE for your agent
MCP serverMCP toolkit giving coding agents symbol-level code retrieval and editing
Runs locally- Open source
- 31.5K GitHub stars
- Developer tools

XERJ
MCP serverLocal search engine for AI agents with cited answers over your code and docs
Runs locally- Open source
- 19.2K GitHub stars
- Knowledge and memory

Ouroboros
MCP serverSpec-first layer that pins requirements and verifies results of AI coding agent work
Runs locally- Open source
- 6.4K GitHub stars
- Developer tools