DEV Community

Nucleus OS
Nucleus OS

Posted on • Originally published at eidetic.works

How to give Claude Code persistent memory across sessions with MCP

#mcp #ai #claude #devtools

Every Claude Code session starts with amnesia. You explain the architecture. You re-explain the decisions. You re-explain why the auth layer looks the way it does. The model nods, does the work, and the next session forgets all of it.

This isn't a model problem. It's a storage problem. The context window resets, and there's nothing persistent for the next session to read from.

I built an MCP server that fixes this. It's called Nucleus, and it gives any MCP-compatible AI client (Claude Code, Cursor, Windsurf, Gemini) a shared, persistent memory layer.

The problem in one screenshot

You open session 2 to continue work from session 1. Session 2 has never heard of session 1. You spend 10 minutes re-explaining what session 1 already knew.

Multiply that by every session, every day, every project. That's the context-drift tax.

What Nucleus does

Nucleus is an MCP server that exposes a small set of tools for writing and querying persistent memory:

  • brain_write_engram — Store a decision, architecture note, or any knowledge with a key, value, context tag, and intensity score.
  • brain_query_engrams — Search stored knowledge by substring, context, or minimum intensity.
  • brain_audit_log — View the cryptographic interaction log for trust verification.
  • brain_governance_status — Check the security and compliance state of the brain.

All data lives in a local .brain/ directory — append-only JSONL files. No cloud, no vendor lock-in. Your memory stays on your machine.

Install in 60 seconds 

pip install nucleus-mcp
nucleus-init --scan
Enter fullscreen mode Exit fullscreen mode

That's it. nucleus-init creates the .brain/ directory, scans your project for a README.md to seed initial context, and auto-configures your MCP clients (Claude Desktop, Cursor, Windsurf).

Restart Claude Code and the tools are available.

Use it in Claude Code

After install, any Claude Code session can write and read from the shared brain:

# Session 1 — you're deciding on the auth architecture
"Use brain_write_engram to store: key='auth_architecture', value='Using OAuth 2.1 with PKCE. Refresh tokens in httpOnly cookies. No server-side sessions.' context='Architecture' intensity=8"

# Session 2 — next day, new context window
"Use brain_query_engrams to search for 'auth' with min_intensity=5"
Enter fullscreen mode Exit fullscreen mode

Session 2 gets back the decision from session 1 without you re-explaining it. The engram persists across sessions, across tools, across machines (if you sync the .brain/ directory).

Why this matters

The context window is not memory. It's short-term recall. Real memory persists when the window resets.

Every AI coding tool has this problem. Claude Code, Cursor, Windsurf, Gemini CLI — they all start each session with zero context. The model is the same. The capabilities are the same. But the knowledge of what you decided yesterday is gone.

Nucleus makes that knowledge durable. One .brain/ directory, shared across all your AI tools, persisted across sessions.

Multi-agent coordination

If you run multiple AI agents (Claude Code + Cursor, or two Claude Code sessions on different parts of the codebase), Nucleus gives them a shared memory. Agent A writes a decision. Agent B reads it. No message queue, no orchestration framework — just a shared file.

The sync tools handle multi-machine coordination:

  • brain_sync_now — Manually trigger a sync
  • brain_sync_status — Check sync state and conflicts
  • brain_identify_agent — Register an agent's identity for attribution

Security model

Nucleus has a hypervisor subsystem that provides OS-level file protection:

  • lock_resource — Lock a file/folder to prevent modification (uses BSD chflags uchg on macOS)
  • watch_resource — Monitor a file/folder for unauthorized changes
  • set_hypervisor_mode — Visual context switching (red/blue/reset)

All operations are logged to a tamper-evident audit log with SHA-256 hashing. The brain_audit_log tool lets you verify the integrity of the interaction history.

What's on PyPI vs what's in the full server

The public nucleus-mcp package on PyPI has 8 tools (memory + governance + hypervisor). The full hosted server at relay.nucleusos.dev has 17 tools including relay coordination, cost routing, and multi-tenant support.

For local-first usage, the PyPI package is all you need. The hosted server is for teams and multi-agent coordination at scale.

Try it 

pip install nucleus-mcp
nucleus-init --scan
Enter fullscreen mode Exit fullscreen mode

Then restart Claude Code and ask it to store a decision. You'll see it persist to .brain/engrams/ledger.jsonl. Open a new session, query it back. That's the whole pitch.

Building in public. The MCP server is open source. The hosted coordination layer is the business. If you're running AI agents seriously, this is the memory layer you're missing.

Top comments (0)