nucleus-mcp 1.0.7 → 1.2.0

package/CHANGELOG.md

@@ -1,65 +0,0 @@
-# Changelog
-
-All notable changes to this project will be documented in this file.
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
-## [1.0.0] - 2025-02-09
-
-### 🎉 Initial Open Source Release
-
-**The Universal Brain for AI Agents** — Cross-platform memory sync for Cursor, Claude Desktop, Windsurf, and any MCP-compatible tool.
-
-### Added
-
-#### Core Features
-- **Persistent Memory** — `brain_write_engram` / `brain_query_engrams` for storing and retrieving knowledge
-- **Audit Trail** — Immutable event log with SHA-256 integrity (`brain_audit_log`)
-- **State Management** — `brain_get_state` / `brain_set_state` for project context
-
-#### Multi-Agent Sync
-- **Cross-Platform Sync** — One brain shared across Cursor, Claude Desktop, Windsurf
-- **Agent Identity** — `brain_identify_agent` for tracking which agent is active
-- **Manual Sync** — `brain_sync_now` to trigger immediate synchronization
-- **Sync Status** — `brain_sync_status` to view sync state and active agents
-
-#### Hypervisor (Security)
-- **File Locking** — `lock_resource` / `unlock_resource` with immutable flags
-- **Resource Watching** — `watch_resource` for monitoring file changes
-- **Security Status** — `hypervisor_status` for system security overview
-
-#### CLI Tools
-- **Smart Init** — `nucleus-init` auto-configures Claude Desktop, Cursor, and Windsurf
-- **Brain Structure** — Creates `.brain/` folder with proper structure
-
-#### Developer Experience
-- MIT License — Fully open source
-- MCP Compatible — Works with any MCP-compatible client
-- Local-First — Your data stays on your machine
-- Zero Cloud Dependencies — No accounts, no telemetry
-
-### Technical Details
-- Python 3.10+ required
-- FastMCP integration for MCP protocol
-- Watchdog for file monitoring
-- Pydantic for data validation
-
----
-
-## Future Roadmap
-
-### [1.1.0] - Planned
-- Auto-sync with file watcher
-- Conflict resolution UI
-- Session persistence improvements
-
-### [1.2.0] - Planned
-- Task management system
-- Multi-agent orchestration
-- Decision provenance (DSoR)
-
-### [2.0.0] - Vision
-- Peer-to-peer federation
-- Enterprise SSO/RBAC
-- Cloud sync option (opt-in)

package/CODE_OF_CONDUCT.md

@@ -1,34 +0,0 @@
-# Contributor Covenant Code of Conduct
-
-## Our Pledge
-
-We as members, contributors, and leaders pledge to make participation in our
-community a harassment-free experience for everyone, regardless of age, body
-size, visible or invisible disability, ethnicity, sex characteristics, gender
-identity and expression, level of experience, education, socio-economic status,
-nationality, personal appearance, race, religion, or sexual identity
-and orientation.
-
-## Our Standards
-
-Examples of behavior that contributes to a positive environment:
-
-* Demonstrating empathy and kindness toward other people
-* Being respectful of differing opinions, viewpoints, and experiences
-* Giving and gracefully accepting constructive feedback
-* Accepting responsibility for mistakes and learning from them
-* Focusing on what is best for the overall community
-
-Examples of unacceptable behavior:
-
-* Harassment, trolling, or personal attacks
-* Publishing others private information without permission
-* Other conduct which could reasonably be considered inappropriate
-
-## Enforcement
-
-Community leaders are responsible for clarifying and enforcing our standards.
-
-## Attribution
-
-This Code of Conduct is adapted from the Contributor Covenant, version 2.0.

package/COMPARISON.md

@@ -1,20 +0,0 @@
-# Nucleus-MCP vs. ContextStream 🧠
-
-When choosing a memory layer for your AI agents, the fundamental question is: **Where does your project's soul live?**
-
-| Feature | Nucleus-MCP | ContextStream |
-| :--- | :--- | :--- |
-| **Philosophy** | **Protocol Level.** Lives inside your tools. | **Platform Level.** Lives on a separate portal. |
-| **Data Ownership** | **Local-First.** Engrams never leave your disk. | **Cloud-Centric.** Managed on their servers. |
-| **Friction** | **Zero.** `pip install` and you're syncing. | **Moderate.** Requires account and platform setup. |
-| **Security** | **Hypervisor Hard-Locks.** L1-L4 safety. | **Managed Guardrails.** Enterprise-policy based. |
-| **IDE Support** | Native (Cursor, Windsurf, VS Code). | Extension/Portal based. |
-| **Governance** | Cryptographic Interaction Ledger. | Dashboards & Reports. |
-
-### Why serious engineers choose Nucleus:
-
-1. **Sovereignty is Binary**: ContextStream asks you to trust their cloud with your architectural secrets. Nucleus doesn't ask for trust—it gives you the keys. 
-2. **Horizontal Interconnect**: We don't want to be your IDE. We make your existing IDEs (Cursor and Windsurf) talk to each other.
-3. **Hard-Tech Governance**: While others show you a "dashboard" of what the agent did, Nucleus provides a **cryptographically signed ledger** of every decision, enforced by a Hypervisor.
-
-**Verdict**: Choose **ContextStream** if you want a collaborative SaaS portal for your team. Choose **Nucleus-MCP** if you want a sovereign, local-first engine that gives your personal agent a permanent, secure brain.

package/CONTRIBUTING.md

@@ -1,137 +0,0 @@
-# Contributing to Nucleus MCP
-
-Thank you for your interest in contributing to Nucleus MCP - The Universal Brain for AI Agents.
-
-## We're Open Source! 🎉
-
-Nucleus is fully open source under the MIT license. We welcome contributions of all kinds:
-
-- ✅ **Bug Reports**: Via GitHub Issues
-- ✅ **Feature Requests**: Via GitHub Discussions
-- ✅ **Code Contributions**: Via Pull Requests
-- ✅ **Documentation**: Improvements always welcome
-- ✅ **Integrations**: Add support for new AI tools
-
-## How to Contribute
-
-### 1. Bug Reports
-
-Found a bug? Please open a GitHub Issue with:
-
-- **Environment**: Python version, OS, MCP client (Claude/Cursor/Windsurf)
-- **Steps to Reproduce**: Minimal example
-- **Expected Behavior**: What should happen
-- **Actual Behavior**: What actually happens
-- **Logs**: Relevant error messages (sanitize sensitive data)
-
-### 2. Feature Requests
-
-Have an idea? Open a GitHub Discussion with:
-
-- **Problem Statement**: What problem does this solve?
-- **Proposed Solution**: How would you implement it?
-- **Alternatives Considered**: What else did you consider?
-- **Use Cases**: Who benefits from this?
-
-### 3. Code Contributions
-
-#### Good First Issues
-
-Look for issues labeled `good-first-issue` - these are ideal for new contributors:
-- Documentation improvements
-- Small bug fixes
-- Test coverage additions
-- New integration examples
-
-#### Development Setup
-
-```bash
-# Clone the repo
-git clone https://github.com/eidetic-works/nucleus-mcp.git
-cd nucleus-mcp
-
-# Create virtual environment
-python3 -m venv venv
-source venv/bin/activate
-
-# Install in development mode
-pip install -e ".[dev]"
-
-# Run tests
-pytest tests/
-```
-
-#### Pull Request Process
-
-1. Fork the repository
-2. Create a feature branch (`git checkout -b feature/amazing-feature`)
-3. Make your changes
-4. Add tests for new functionality
-5. Ensure all tests pass (`pytest tests/`)
-6. Run linting (`ruff check src/`)
-7. Commit with clear messages
-8. Push to your fork
-9. Open a Pull Request
-
-#### PR Review Criteria
-
-- [ ] Tests pass
-- [ ] Code follows existing style
-- [ ] Documentation updated if needed
-- [ ] No breaking changes (or clearly documented)
-
-### 4. Documentation
-
-Documentation improvements are always welcome:
-
-- Typo fixes
-- Clarification of existing docs
-- New examples or tutorials
-- Integration guides for new tools
-
-## Code of Conduct
-
-### Be Respectful
-- Treat everyone with respect
-- No harassment, discrimination, or personal attacks
-- Assume good intent
-
-### Be Constructive
-- Provide actionable feedback
-- Focus on the problem, not the person
-- Celebrate successes
-
-### Be Patient
-- Maintainers are volunteers
-- Response times may vary
-- Quality over speed
-
-## Security Vulnerabilities
-
-**Do NOT report security vulnerabilities via public GitHub Issues.**
-
-Instead, email: security@nucleusos.dev
-
-Include:
-- Detailed description of the vulnerability
-- Steps to reproduce
-- Potential impact
-- Any suggested fixes
-
-We follow responsible disclosure and will credit researchers who report valid vulnerabilities.
-
-## License
-
-By contributing to Nucleus MCP, you agree that your contributions will be licensed under the MIT License.
-
-## Questions?
-
-- **General Questions**: GitHub Discussions
-- **Bug Reports**: GitHub Issues
-- **Security**: security@nucleusos.dev
-
----
-
-*Thank you for helping make Nucleus better!*
-
-*— The Nucleus Team*

package/DEVELOPMENT.md

@@ -1,109 +0,0 @@
-# Development Workflow
-
-## Branch Strategy
-
-```
-main (protected)
-  └── dev (integration branch)
-       ├── feature/xxx
-       └── fix/xxx
-```
-
-### Branches
-
-| Branch | Purpose | Merges To |
-|--------|---------|-----------|
-| `main` | Production-ready, PyPI releases | - |
-| `dev` | Integration, testing | `main` (via PR) |
-| `feature/*` | New features | `dev` (via PR) |
-| `fix/*` | Bug fixes | `dev` (via PR) |
-
-## Development Setup
-
-```bash
-# Clone
-git clone https://github.com/eidetic-works/nucleus-mcp.git
-cd nucleus-mcp
-
-# Create dev branch (if not exists)
-git checkout -b dev
-git push -u origin dev
-
-# Create feature branch
-git checkout dev
-git pull origin dev
-git checkout -b feature/my-feature
-
-# Work on feature...
-git add .
-git commit -m "feat: description"
-git push -u origin feature/my-feature
-
-# Create PR to dev branch
-```
-
-## Local Testing
-
-```bash
-# Create virtual environment
-python3 -m venv .venv
-source .venv/bin/activate
-
-# Install in development mode
-pip install -e ".[dev]"
-
-# Run tests
-pytest tests/ -v
-
-# Type checking
-mypy src/
-
-# Linting
-ruff check src/
-```
-
-## Release Process
-
-1. Ensure all features merged to `dev`
-2. Create PR from `dev` → `main`
-3. Review and merge
-4. Tag release: `git tag v1.x.x && git push --tags`
-5. Publish to PyPI:
-   ```bash
-   python -m build
-   twine upload dist/*
-   ```
-
-## Internal Work Separation
-
-### What Goes in This Repo (PUBLIC)
-- Core MCP server code (`src/`)
-- Tests (`tests/`)
-- Examples (`examples/`)
-- Public documentation (`docs/DEMO_SCRIPT.md`)
-- Standard files (README, LICENSE, etc.)
-
-### What Stays Local (NEVER COMMIT)
-- Launch strategy docs (keep in a separate local folder, NOT in this repo)
-- Internal roadmaps
-- GTM documents
-- Outreach plans
-- Any `.md` matching patterns in `.gitignore`
-
-## Pre-Push Checklist
-
-```bash
-# Before pushing, always verify:
-git status                    # No unwanted files staged
-git diff --cached --name-only # Review what's being committed
-```
-
-## Protected Files (via .gitignore)
-
-The following patterns are blocked from commits:
-- `docs/*LAUNCH*.md`
-- `docs/*STRATEGY*.md`
-- `*_INTERNAL.md`
-- `*_PRIVATE.md`
-- `GTM*.md`
-- `OUTREACH*.md`

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2025 Nucleus Team
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.

package/README.md

@@ -1,319 +0,0 @@
-# 🧠 Nucleus MCP
-
-[![PyPI version](https://img.shields.io/pypi/v/nucleus-mcp?color=brightgreen&label=pypi%20package)](https://pypi.org/project/nucleus-mcp/)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-brightgreen)](https://modelcontextprotocol.io)
-[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
-
-> [!CAUTION]
-> **After the [OpenClaw security crisis](https://www.youtube.com/watch?v=ceEUO_i7aW4) (1.5M API keys leaked, sleeper agents in skills), agent security is no longer optional.**
-> Nucleus was built security-first: Hypervisor controls, resource locking, and full audit trails — all 100% local.
-
-> **The Sovereign Brain** — Cross-platform AI memory that never leaves your machine. Syncs Cursor, Claude Desktop, Windsurf, and any MCP-compatible tool.
-
----
-
-## 🎯 The Problem
-
-You use **multiple AI tools** daily:
-- **Cursor** for coding
-- **Claude Desktop** for thinking
-- **Windsurf** for exploration
-- **ChatGPT** for quick reasoning
-
-**But they don't share memory. (Until now).**
-
-Every time you switch tools, you lose context. You re-explain decisions. You repeat yourself constantly.
-
----
-
-### ✨ The Solution
-
-**Nucleus syncs them with one brain.**
-
-```
-Tell Claude about a decision → Cursor knows it
-Make a plan in Windsurf → Claude remembers it
-One brain. All your tools.
-```
-
-![Recursive Snap Demo](docs/RECURSIVE_SNAP_DEMO.gif)
-
-> [!TIP]
-> **See the "Recursive Snap" in action**: Nucleus mounts your entire tool mesh (Stripe, Search, Postgres) into a single governed parent instantly.
-
----
-
-## 🚀 What Makes Nucleus Different
-
-| Feature | Other Solutions | Nucleus |
-|---------|-----------------|---------|
-| **Cross-Platform Sync** | Single platform only | ✅ Syncs ALL your AI tools |
-| **Sovereignty** | Cloud-dependent | ✅ 100% local, your data stays on your machine |
-| **Protocol** | Proprietary | ✅ MCP standard (Anthropic-backed) |
-| **Security** | Often misconfigured | ✅ Secure by default, audit logs included |
-| **Lock-in** | Platform-specific | ✅ MIT license, open standard |
-
----
-
-## ⚡ Quick Start (2 Minutes)
-
-### 1. Install
-
-```bash
-pip install nucleus-mcp
-```
-
-### 2. Initialize
-
-```bash
-nucleus-init --scan
-```
-
-This creates your `.brain/` folder, auto-configures Claude Desktop, and **automatically ingests your README.md** to seed the brain with initial context.
-
-### 3. Restart Claude Desktop
-
-Then try:
-> "What decisions have we made about the architecture?"
-
-Claude will now remember across sessions!
-
----
-
-## 🔧 Manual Configuration
-
-### Claude Desktop
-
-Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):
-
-```json
-{
-  "mcpServers": {
-    "nucleus": {
-      "command": "python3",
-      "args": ["-m", "mcp_server_nucleus"],
-      "env": {
-        "NUCLEAR_BRAIN_PATH": "/path/to/your/project/.brain"
-      }
-    }
-  }
-}
-```
-
-### Cursor
-
-Add to `~/.cursor/mcp.json`:
-
-```json
-{
-  "mcpServers": {
-    "nucleus": {
-      "command": "python3",
-      "args": ["-m", "mcp_server_nucleus"],
-      "env": {
-        "NUCLEAR_BRAIN_PATH": "/path/to/your/project/.brain"
-      }
-    }
-  }
-}
-```
-
-### Windsurf
-
-Add to `~/.codeium/windsurf/mcp_config.json`:
-
-```json
-{
-  "mcpServers": {
-    "nucleus": {
-      "command": "python3",
-      "args": ["-m", "mcp_server_nucleus"],
-      "env": {
-        "NUCLEAR_BRAIN_PATH": "/path/to/your/project/.brain"
-      }
-    }
-  }
-}
-```
-
-### ChatGPT (Web)
-
-1. Go to **Settings** → **Apps** → **Advanced** → **Developer Mode**.
-2. Run the Nucleus SSE Bridge: `python scripts/sse_bridge.py`.
-3. Add `http://localhost:8000/sse` as your MCP endpoint.
-
-See the [Community FAQ](docs/COMMUNITY_FAQ.md) for more details.
-
----
-
-## 🛠 Core Tools
-
-### Memory
-| Tool | Description |
-|------|-------------|
-| `brain_write_engram` | Store persistent knowledge |
-| `brain_query_engrams` | Retrieve knowledge |
-| `brain_audit_log` | View decision history |
-
-### Sync (Multi-Agent)
-| Tool | Description |
-|------|-------------|
-| `brain_sync_now` | Manually trigger brain sync |
-| `brain_sync_status` | Check sync state and conflicts |
-| `brain_sync_auto` | Enable/disable auto-sync |
-| `brain_identify_agent` | Register agent identity |
-
-### State Management
-| Tool | Description |
-|------|-------------|
-| `brain_get_state` | Get current project state |
-| `brain_set_state` | Update project state |
-| `brain_list_artifacts` | List all artifacts |
-
-### Hypervisor (Security)
-| Tool | Description |
-|------|-------------|
-| `lock_resource` | Lock file/folder (immutable) |
-| `unlock_resource` | Unlock resource |
-| `watch_resource` | Monitor file changes |
-| `hypervisor_status` | View security state |
-
----
-
-## 🔄 Multi-Agent Sync (The Killer Feature)
-
-**Multiple agents, one brain.**
-
-```python
-# Agent A (Claude Desktop) makes a decision
-brain_sync_now()  # Syncs to shared .brain/
-
-# Agent B (Cursor) automatically sees it
-brain_sync_status()  # Shows last sync, active agents
-```
-
-**Features:**
-- **Intent-Aware Locking** — Files locked with WHO/WHEN/WHY metadata
-- **Conflict Detection** — Last-write-wins with manual resolution option
-- **Auto-Sync** — Optional file watcher for real-time sync
-- **Audit Trail** — Every sync logged to `events.jsonl`
-
----
-
-## ⚔️ Comparison: Nucleus vs Alternatives
-
-| | OpenClaw | Claude Code | Nucleus |
-|---|----------|-------------|---------|
-| **What it syncs** | OpenClaw → OpenClaw | Claude → Claude | **Everything ↔ Everything** |
-| **Security** | ❌ Sleeper agents, key leaks | ⚠️ Cloud-managed | ✅ Hypervisor + audit trail |
-| **Cross-platform** | ❌ | ❌ | ✅ |
-| **Local-first** | ⚠️ Some cloud | ⚠️ Some cloud | ✅ 100% local |
-| **Identity Persistence** | ❌ Session-bound | ❌ Login-bound | ✅ Hypervisor-enforced |
-| **MCP Native** | ❌ Custom protocol | ⚠️ Limited | ✅ Full MCP |
-| **Open Source** | ✅ MIT | ❌ Closed | ✅ MIT |
-
----
-
-## 🔗 Technical Deep Dives
-
-*   **Forensics**: [How we trace agent intent at the kernel level](https://dev.to/nucleusos/how-i-synced-cursor-claude-and-windsurf-with-one-shared-brain-mcp-1mh4)
-*   **Philosophy**: [Why we abandoned cloud memory for local sovereignty](https://dev.to/nucleusos/why-we-abandoned-cloud-memory-for-local-sovereignty-5bbo)
-
-**OpenClaw is great for multi-agent teams on their platform.**
-**OpenClaw trades security for capability. Nucleus gives you both.**
-
-> [!TIP]
-> **Check out the [Detailed Comparison](docs/COMPETITIVE_ANALYSIS.md)** to see how Nucleus stacks up against ContextStream and other alternatives.
-
----
-
-## 📁 The `.brain/` Folder
-
-Nucleus stores everything in a `.brain/` folder in your project:
-
-```
-.brain/
-├── config/
-│   └── nucleus.yaml      # Configuration
-├── ledger/
-│   ├── state.json        # Current state
-│   ├── events.jsonl      # Audit log
-│   └── decisions.md      # Decision history
-├── artifacts/
-│   └── ...               # Your stored knowledge
-└── sessions/
-    └── ...               # Saved sessions
-```
-
-**Your data. Your machine. Your control.**
-
----
-
-## 🤝 Contributing
-
-We're building the universal brain for AI agents. Join us!
-
-- **🐛 Found a bug?** Open an [Issue](https://github.com/eidetic-works/nucleus-mcp/issues)
-- **💡 Feature idea?** Start a [Discussion](https://github.com/eidetic-works/nucleus-mcp/discussions)
-- **🔧 Want to contribute?** See [CONTRIBUTING.md](CONTRIBUTING.md)
-
-### ✨ Pioneers & Contributors
-
-Nucleus is a community-first project. A special thank you to our first contributor for setting the standard:
-
-- **[@aryasadawrate19](https://github.com/aryasadawrate19)** — Added Linux XDG support for `nucleus-init`, bringing Nucleus to the Linux ecosystem.
-
-*Want to be here? See [CONTRIBUTING.md](CONTRIBUTING.md) and claim a "Good First Issue".*
-
-### Development Setup
-
-```bash
-git clone https://github.com/eidetic-works/nucleus-mcp.git
-cd nucleus-mcp
-python3 -m venv venv
-source venv/bin/activate
-pip install -e ".[dev]"
-pytest tests/
-```
-
-## 🏢 Enterprise
-
-Nucleus is built for organizations that cannot compromise on data sovereignty:
-
-- **Air-Gap Ready**: Deploy in fully disconnected environments
-- **Compliance First**: Full audit trail, SHA-256 hashing, ITAR/SOC2 ready
-- **Team Sync**: Git-based knowledge sharing (coming soon)
-
-📄 **[Enterprise Guide](docs/ENTERPRISE.md)** | 📊 **[Competitive Analysis](docs/COMPETITIVE_ANALYSIS.md)**
-
-**Contact**: [enterprise@nucleusos.dev](mailto:enterprise@nucleusos.dev)
-
----
-
-## 🛡️ Join the Nucleus Vanguard (Private Beta)
-
-We're building the first secure sync layer for agents. Join our Vanguard Pioneers to help shape the roadmap and get early access to features before they go public.
-
-**[Join the Nucleus Vanguard (Discord)](https://discord.gg/RJuBNNJ5MT)** | **[Visit Website](https://nucleusos.dev)**
-
-> [!TIP]
-> The Vanguard is currently open for early adopters. Introduce yourself in the `#welcome-start` channel to claim your **Vanguard Pioneer** role and join the inner circle.
-
----
-
-## 📜 License
-
-MIT © Nucleus Team
-
----
-
-## ⭐ Support
-
-**Star us on GitHub if Nucleus saves you from context amnesia!**
-
-One brain. All your AI tools. No more repeating yourself.
-
----
-
-*Built for the AI-native developer.*