nucleus-mcp 1.0.7 → 1.2.0

package/ROADMAP.md

@@ -1,24 +0,0 @@
-# Nucleus MCP Roadmap 🧠
-
-This roadmap reflects our commitment to **Sovereign Intelligence** and the transition to a **Sovereign Swarm** governance model.
-
-## 🟢 Q1 2026: Foundation & Sync
-- **Universal Sync**: Finalize memory synchronization between Cursor, Claude Desktop, and Windsurf.
-- **Engram V2**: High-intensity cognitive persistence.
-- **Governance Tools**: Layer 0-3 visibility for agent decisions.
-- **Community Launch**: Establish the "Pioneer" contributor base.
-
-## 🟡 Q2 2026: The Sovereign Swarm
-- **Guardian Network**: Delegate sub-module ownership (Linux, macOS, Security).
-- **Federated Memory**: Cross-machine engram syncing for individual users.
-- **Hypervisor L4/L5**: Advanced hard-locks for agentic file/process control.
-- **Nucleus Bridge (ChatGPT)**: Secure tunnel for cloud-hosted agents (ChatGPT/OpenAI) to access local brain.
-- **Public API**: Stable standard for external MCP server mounting.
-
-## 🔴 Q3 2026+: Autonomy & Scale
-- **Peer-to-Peer Sovereignty**: Decentralized discovery of other user brains.
-- **Swarm Council**: Full transition to community-voted protocol updates.
-- **Agent Economy**: Integration with metering and local-first billing models.
-
----
-*Roadmap is evolved through our [Sovereign Swarm Discussions](https://github.com/eidetic-works/nucleus-mcp/discussions).*

package/SECURITY.md

@@ -1,88 +0,0 @@
-# Security Policy
-
-## Supported Versions
-
-| Version | Supported          |
-| ------- | ------------------ |
-| 1.0.x   | ✅ Yes             |
-| < 1.0   | ❌ No              |
-
-## Reporting a Vulnerability
-
-**Do NOT report security vulnerabilities via public GitHub Issues.**
-
-### How to Report
-
-1. **Email**: security@nucleusos.dev
-2. **Subject**: `[SECURITY] Brief description`
-3. **Include**:
-   - Detailed description of the vulnerability
-   - Steps to reproduce
-   - Potential impact assessment
-   - Any suggested fixes (optional)
-
-### What to Expect
-
-- **Acknowledgment**: Within 48 hours
-- **Initial Assessment**: Within 7 days
-- **Resolution Timeline**: Varies by severity
-  - Critical: 24-72 hours
-  - High: 1-2 weeks
-  - Medium: 2-4 weeks
-  - Low: Next release cycle
-
-### Responsible Disclosure
-
-We follow responsible disclosure practices:
-
-1. We will acknowledge your report within 48 hours
-2. We will provide an estimated timeline for the fix
-3. We will notify you when the vulnerability is fixed
-4. We will credit you in the release notes (unless you prefer anonymity)
-
-## Security Best Practices
-
-### For Users
-
-1. **Keep Nucleus Updated**: Always use the latest version
-2. **Protect Your `.brain/` Folder**: Contains your project context
-3. **Review Audit Logs**: Check `events.jsonl` for suspicious activity
-4. **Use File Locking**: Lock critical files during sensitive operations
-
-### For Contributors
-
-1. **No Hardcoded Secrets**: Never commit API keys, tokens, or credentials
-2. **Input Validation**: Validate all user inputs
-3. **Path Traversal**: Prevent directory traversal attacks
-4. **Dependency Auditing**: Keep dependencies updated
-
-## Security Features
-
-Nucleus includes several security features:
-
-- **Local-First Architecture**: Your data never leaves your machine
-- **Audit Trail**: Every action logged to `events.jsonl`
-- **File Locking**: Hypervisor-level immutable locks
-- **Intent-Aware Metadata**: Know WHO locked WHAT and WHY
-
-## Known Security Considerations
-
-### MCP Protocol
-
-Nucleus operates as an MCP server. Be aware that:
-
-- MCP clients (Claude, Cursor, etc.) have full access to exposed tools
-- Environment variables may contain sensitive paths
-- The `.brain/` folder should be treated as sensitive data
-
-### Multi-Agent Sync
-
-When using multi-agent sync:
-
-- All agents with access to `.brain/` can read/write data
-- Sync conflicts are resolved via last-write-wins by default
-- Consider file locking for critical operations
-
----
-
-*Security is a shared responsibility. Thank you for helping keep Nucleus safe.*

package/docs/COMMUNITY_FAQ.md

@@ -1,48 +0,0 @@
-# Nucleus MCP: Community FAQ
-
-## General Questions
-
-### Q: What is Nucleus MCP?
-**A:** Nucleus MCP is a Model Context Protocol (MCP) server that acts as a "Universal Brain" for AI agents. It provides a shared, persistent memory layer that works across multiple AI tools like Claude Desktop, Cursor, and Windsurf.
-
-### Q: Why do I need it?
-**A:** Most AI tools started from scratch with every new conversation. Nucleus allows you to save context (decisions, project state, tasks) in a local `.brain/` folder that survives session restarts and is shared across all your AI assistants.
-
----
-
-## Tool Compatibility
-
-### Q: How do I use it with ChatGPT?
-**A:** ChatGPT now supports MCP in its **Developer Beta Mode** (Web Browser).
-1. Go to ChatGPT Settings → Apps → Advanced.
-2. Enable **Developer Mode**.
-3. Use the Nucleus SSE Bridge (see below) to connect your local brain to the web interface.
-
-**Note:** For a quick manual sync, you can always copy the contents of your `.brain/state.md` and paste it into ChatGPT.
-
-### Q: Does it work with Cursor / Windsurf?
-**A:** Yes! Nucleus is designed specifically for these tools. Running `nucleus-init` will automatically update your `project.json` or equivalent config files to register the Nucleus MCP server.
-
-### Q: Is my data safe?
-**A:** 100%. Nucleus is local-first. All your data stays in the `.brain/` folder on your own machine. There is no cloud storage, no telemetry, and no data tracking.
-
----
-
-## Technical Questions
-
-### Q: How do I install it?
-**A:** 
-```bash
-pip install nucleus-mcp
-nucleus-init
-```
-
-### Q: What's the difference between an "Engram" and a "Task"?
-**A:** 
-- **Engram:** Persistent knowledge or an architectural decision (long-term memory).
-- **Task:** A specific actionable item (operational memory).
-Nucleus manages both to give your AI a complete picture of your project's past and future.
-
----
-
-*Found a bug or have a request? Open an issue on [GitHub](https://github.com/eidetic-works/nucleus-mcp)!*

package/docs/COMPETITIVE_ANALYSIS.md

@@ -1,90 +0,0 @@
-# Nucleus MCP: Competitive Analysis
-
-## Market Positioning
-
-**Nucleus Tagline:** "The Sovereign Brain — Cross-platform AI memory that never leaves your machine"
-
----
-
-## Feature Comparison Matrix
-
-| Feature | Nucleus MCP | ContextStream | OpenClaw | mem0 | Graphiti |
-|---------|-------------|---------------|----------|------|----------|
-| **Local-First** | ✅ 100% local | ❌ Cloud-based | ❌ Cloud bridge | ⚠️ Partial | ⚠️ Partial |
-| **Cross-Platform Sync** | ✅ All MCP tools | ⚠️ Limited | ❌ Claude only | ❌ Single | ❌ Single |
-| **Open Source (MIT)** | ✅ Full | ❌ Proprietary | ⚠️ Partial | ✅ | ✅ |
-| **Recursive MCP Mount** | ✅ Unique | ❌ | ❌ | ❌ | ❌ |
-| **Cryptographic Audit** | ✅ Built-in | ❌ | ❌ | ❌ | ❌ |
-| **No Account Required** | ✅ | ❌ Login needed | ❌ | ✅ | ✅ |
-| **Enterprise Compliance** | ✅ Air-gap ready | ❌ Cloud only | ❌ | ⚠️ | ⚠️ |
-| **Stability** | ✅ Production | ✅ Production | ⚠️ Hype stage | ⚠️ Buggy | ⚠️ Buggy |
-
----
-
-## Competitive Advantages
-
-### vs ContextStream
-- **Sovereignty**: ContextStream requires cloud; Nucleus is 100% local
-- **Privacy**: No data leaves your machine with Nucleus
-- **Enterprise**: Nucleus works in air-gapped environments
-- **Cost**: Nucleus is free forever (MIT); ContextStream has pricing tiers
-
-### vs OpenClaw
-- **Multi-Platform**: OpenClaw only bridges Claude; Nucleus syncs ALL MCP tools
-- **Security**: Post-OpenClaw crisis, Nucleus was built security-first
-- **Maturity**: Nucleus is production-ready; OpenClaw sentiment: "just hype"
-
-### vs mem0/Graphiti
-- **Quality**: Both have "incredibly evident bugs" (Reddit feedback)
-- **Cross-Platform**: Neither supports multi-IDE sync
-- **Features**: Nucleus includes orchestration (recursive mount), not just memory
-
----
-
-## Target Personas
-
-### 1. Multi-IDE Power User
-- Uses Cursor + Claude + Windsurf daily
-- Pain: Context lost when switching tools
-- Why Nucleus: Only solution syncing all platforms
-
-### 2. Privacy-Conscious Developer
-- Works at security-sensitive companies
-- Can't use cloud solutions
-- Why Nucleus: 100% local, no account needed
-
-### 3. Enterprise/Government
-- Requires air-gap deployment
-- Compliance requirements (ITAR, etc.)
-- Why Nucleus: Full audit trail, no cloud dependency
-
----
-
-## Market Validation (Reddit Signals)
-
-| Signal | Source | Engagement |
-|--------|--------|------------|
-| "MCP server that gives local LLMs memory, 100% offline" | r/LocalLLaMA | 315+ upvotes |
-| "Basic Memory: open source, local-first AI memory" | r/selfhosted | Popular post |
-| "odyssey trying to set up memory server... graphiti, mem0 have bugs" | r/AgentsOfAI | Pain validated |
-| "biggest pain point was memory — agent forgets between sessions" | r/selfhosted | Exact pain |
-
----
-
-## Messaging Framework
-
-### One-Liner
-> "The only AI memory that syncs across IDEs without leaving your machine"
-
-### Elevator Pitch
-> Nucleus is the sovereign brain for AI agents. While competitors like ContextStream send your code to the cloud, Nucleus keeps everything local. While OpenClaw only works with Claude, Nucleus syncs Cursor, Claude, Windsurf, and any MCP tool. One brain, all your tools, 100% your data.
-
-### Key Differentiators (In Order)
-1. **Local-First Sovereignty** — Your data never leaves your machine
-2. **Cross-Platform Sync** — The ONLY solution syncing multiple AI tools
-3. **Security-First** — Built after learning from OpenClaw's failures
-4. **Open Standard** — MIT license, MCP protocol, no lock-in
-
----
-
-*Generated: Feb 2026 | Source: Design Thinking Battle Test*

package/docs/DEMO_SCRIPT.md

@@ -1,86 +0,0 @@
-# Nucleus MCP Demo Video Script
-
-## Original Script (Use This)
-
-> "What if your AI assistants could remember everything... and work together?
->
-> Every Claude conversation starts from zero. No memory. No coordination. You repeat yourself constantly.
->
-> Introducing Nucleus. The core of your AI agents. One command. Persistent memory.
->
-> Available now on PyPI. Ten powerful tools for agent orchestration. MCP Resources and Prompts included.
->
-> Open source. MIT licensed. Works with Claude Desktop out of the box.
->
-> Watch this. I ask Claude about my sprint... it calls brain_get_state... and returns my actual project context.
->
-> List my artifacts. Instant access to all my research, strategies, and outputs.
->
-> Give your AI agents a brain. Install Nucleus today. Star on GitHub if you find it useful."
-
----
-
-## Video Timestamps (58 seconds total)
-
-| Time | Visual | Script |
-|------|--------|--------|
-| 0:00-0:05 | Claude Desktop opening | "What if your AI assistants could remember everything..." |
-| 0:05-0:12 | Claude saying "I don't have access" | "Every Claude conversation starts from zero..." |
-| 0:12-0:18 | Terminal: pip install | "Introducing Nucleus. One command." |
-| 0:18-0:25 | Nucleus logo/branding | "Available now on PyPI. Ten powerful tools..." |
-| 0:25-0:32 | Config file | "Open source. MIT licensed." |
-| 0:32-0:45 | Claude using brain_get_state | "Watch this. I ask Claude about my sprint..." |
-| 0:45-0:52 | Artifact listing | "List my artifacts. Instant access..." |
-| 0:52-0:58 | GitHub repo + CTA | "Give your AI agents a brain. Install Nucleus today." |
-
----
-
-## Key Changes for Open Source Version
-
-The original demo video is **perfect for the open source launch**. No changes needed because:
-
-1. ✅ Shows the core value prop (persistent memory)
-2. ✅ Shows pip install (same command)
-3. ✅ Shows Claude Desktop integration
-4. ✅ Mentions "Open source. MIT licensed."
-5. ✅ Shows real tool usage (brain_get_state, artifacts)
-
-**The video can be used as-is.**
-
----
-
-## Call to Action Updates
-
-Update the end screen to show:
-
-```
-🧠 Nucleus MCP
-
-pip install nucleus-mcp
-nucleus-init
-
-github.com/eidetic-works/nucleus-mcp
-
-⭐ Star us on GitHub!
-```
-
----
-
-## Thumbnail Suggestions
-
-Option A: Split brain visual with "One Brain. All Your AI Tools."
-Option B: Logos of Cursor + Claude + Windsurf with sync arrows
-Option C: Terminal showing `pip install nucleus-mcp` with brain emoji
-
----
-
-## Distribution Plan
-
-1. **YouTube**: Full 58-second version
-2. **Twitter/X**: 45-second cut (skip config section)
-3. **Reddit**: GIF version (no audio, with captions)
-4. **GitHub README**: GIF or embedded YouTube
-
----
-
-*The existing demo video from 1 month ago is ready for the open source launch.*

package/docs/ENTERPRISE.md

@@ -1,169 +0,0 @@
-# Nucleus MCP: Enterprise Guide
-
-## Overview
-
-Nucleus MCP is designed for organizations that cannot compromise on data sovereignty. This guide covers enterprise deployment, compliance, and security features.
-
----
-
-## Enterprise Features
-
-### 🔒 Air-Gap Ready
-
-Deploy Nucleus in fully disconnected environments:
-
-- **Zero Cloud Calls**: No external API requests, no telemetry
-- **No Internet Required**: Runs entirely on local machine
-- **Portable**: Copy `.brain/` folder to any machine
-
-```bash
-# Air-gap installation
-pip install nucleus-mcp --no-deps
-# Or from wheel
-pip install nucleus_mcp-1.0.5-py3-none-any.whl
-```
-
-### 📋 Compliance First
-
-Built for regulated industries:
-
-- **Full Audit Trail**: Every agent interaction logged with timestamps
-- **Cryptographic Hashing**: SHA-256 signatures on critical operations
-- **Decision Provenance**: Track exactly why each decision was made
-- **Export Capability**: Generate compliance reports from `.brain/ledger/`
-
-**Supported Frameworks:**
-- SOC 2 Type II
-- ITAR (International Traffic in Arms Regulations)
-- GDPR (data never leaves your infrastructure)
-- HIPAA (when deployed on compliant infrastructure)
-
-### 👥 Team Sync (Coming Soon)
-
-Share knowledge across your team without cloud dependencies:
-
-- **Git-Based Sync**: Commit `.brain/` to your repo
-- **Conflict Resolution**: CRDT-based merge for concurrent edits
-- **Role-Based Access**: Control who can read/write engrams
-- **Branch Isolation**: Separate context per feature branch
-
----
-
-## Deployment Options
-
-### Option 1: Per-Developer Installation
-
-Each developer installs Nucleus locally:
-
-```bash
-pip install nucleus-mcp
-nucleus-init
-```
-
-**Pros:** Maximum isolation, no shared state
-**Cons:** No cross-team learning
-
-### Option 2: Shared Repository
-
-Team shares `.brain/` via git:
-
-```bash
-# In team repo
-git add .brain/
-git commit -m "Sync team memory"
-```
-
-**Pros:** Shared learnings, decision history
-**Cons:** Merge conflicts possible
-
-### Option 3: Network Share (Air-Gap)
-
-Mount `.brain/` on network drive:
-
-```bash
-export NUCLEAR_BRAIN_PATH=/mnt/shared/nucleus-brain
-nucleus-mcp
-```
-
-**Pros:** Real-time sharing, air-gap compatible
-**Cons:** Requires file locking discipline
-
----
-
-## Security Architecture
-
-```
-┌─────────────────────────────────────────┐
-│          Your Infrastructure            │
-│  ┌─────────────────────────────────┐    │
-│  │         Nucleus MCP             │    │
-│  │  ┌─────────┐  ┌─────────────┐   │    │
-│  │  │ Engrams │  │ Audit Logs  │   │    │
-│  │  │ (Memory)│  │ (SHA-256)   │   │    │
-│  │  └─────────┘  └─────────────┘   │    │
-│  │  ┌─────────────────────────┐    │    │
-│  │  │    Hypervisor Layer     │    │    │
-│  │  │  - Default Deny Policy  │    │    │
-│  │  │  - Resource Locking     │    │    │
-│  │  │  - IPC Authentication   │    │    │
-│  │  └─────────────────────────┘    │    │
-│  └─────────────────────────────────┘    │
-│                                         │
-│  ╔═════════════════════════════════╗    │
-│  ║   NO DATA LEAVES THIS BOX       ║    │
-│  ╚═════════════════════════════════╝    │
-└─────────────────────────────────────────┘
-```
-
-### Default Deny Policy
-
-All mounted MCP servers start with zero permissions:
-- No network access
-- No filesystem access outside `.brain/`
-- No cross-server communication
-
-Trust is explicitly granted via governance rules.
-
-### IPC Authentication
-
-Inter-process communication secured via:
-- Per-session secret tokens
-- Process ID verification
-- Timeout-based invalidation
-
----
-
-## Support & Custom Deployments
-
-For enterprise inquiries:
-
-- **Email**: enterprise@nucleusos.dev
-- **Custom Deployments**: On-premise installation support
-- **Priority Support**: SLA guarantees available
-- **Training**: Team onboarding sessions
-
----
-
-## FAQ
-
-**Q: Can Nucleus run without internet?**
-A: Yes. Nucleus is 100% local-first. No cloud dependencies.
-
-**Q: How do I export audit logs for compliance?**
-A: Audit logs are in `.brain/ledger/events.jsonl`. Export with:
-```bash
-cp .brain/ledger/events.jsonl /path/to/compliance/report/
-```
-
-**Q: Is Nucleus HIPAA compliant?**
-A: Nucleus stores all data locally. HIPAA compliance depends on your infrastructure. We provide the tools; you control the environment.
-
-**Q: How do I integrate with existing MCP servers?**
-A: Use the recursive mount feature:
-```python
-brain_mount_server(mount_id="my-server", command="npx", args=["my-mcp-server"])
-```
-
----
-
-*Nucleus MCP: The Sovereign Brain for Enterprise AI*