nucleus-mcp 1.0.7 → 1.2.0

package/docs/FAQ.md

@@ -1,228 +0,0 @@
-# Nucleus MCP: Frequently Asked Questions
-
-## General
-
-### What is Nucleus MCP?
-
-Nucleus is a local-first, cross-platform memory system for AI coding assistants. It syncs your context, decisions, and learnings across Claude Desktop, Cursor, Windsurf, and any MCP-compatible tool.
-
-### Why should I use Nucleus instead of just using each tool separately?
-
-Every time you switch between AI tools, you lose context. You re-explain your codebase, repeat decisions, and waste time. Nucleus creates one "brain" that all your tools share, so they remember everything together.
-
-### Is Nucleus free?
-
-Yes. Nucleus is MIT licensed and 100% free. No subscription, no account required, no cloud fees.
-
----
-
-## Privacy & Security
-
-### Does Nucleus send my data to the cloud?
-
-**No.** Nucleus is 100% local-first. All your data stays in the `.brain/` folder on your machine. Zero cloud calls, zero telemetry.
-
-### Where is my data stored?
-
-By default, your data is stored in `~/.brain/` (or `$NUCLEAR_BRAIN_PATH` if set). This includes:
-- `engrams/` - Your memories and learnings
-- `ledger/` - Audit trail and task history
-- `state.json` - Current session state
-
-### Can I back up my Nucleus data?
-
-Yes! Just copy your `.brain/` folder. You can also commit it to git for version control:
-
-```bash
-cd ~/.brain
-git init
-git add .
-git commit -m "Backup brain"
-```
-
-### Is Nucleus HIPAA/SOC2 compliant?
-
-Nucleus stores all data locally, which satisfies data residency requirements. Full compliance depends on your infrastructure and policies. See [ENTERPRISE.md](ENTERPRISE.md) for details.
-
----
-
-## Installation
-
-### What are the system requirements?
-
-- Python 3.10+
-- Any MCP-compatible tool (Claude Desktop, Cursor, Windsurf)
-- ~10MB disk space for the package
-- Minimal RAM usage (runs as a subprocess)
-
-### I installed Nucleus but my AI tool doesn't see it
-
-1. Restart your AI tool completely
-2. Check your MCP config file includes Nucleus
-3. Run `nucleus-init` again to reconfigure
-4. Verify with: `python -c "from mcp_server_nucleus import brain_health; print(brain_health())"`
-
-### How do I update Nucleus?
-
-```bash
-pip install --upgrade nucleus-mcp
-```
-
----
-
-## Usage
-
-### What are "engrams"?
-
-Engrams are Nucleus's memory units. Each engram has:
-- **Key**: Unique identifier
-- **Value**: The actual content/memory
-- **Context**: Category (Feature, Architecture, Brand, Strategy, Decision)
-- **Intensity**: Importance (1-10)
-
-### How do I write a memory?
-
-Via MCP tool in your AI assistant:
-```
-brain_write_engram(key="my_decision", value="Chose React for frontend", context="Architecture", intensity=7)
-```
-
-### How do I retrieve memories?
-
-```
-brain_query_engrams(context="Architecture", min_intensity=5)
-```
-
-This returns all Architecture engrams with intensity >= 5.
-
-### What's the difference between contexts?
-
-| Context | Use For | Example |
-|---------|---------|---------|
-| `Feature` | Product features | "Added dark mode toggle" |
-| `Architecture` | Technical decisions | "Using PostgreSQL for persistence" |
-| `Brand` | Messaging, positioning | "Tagline: The Sovereign Brain" |
-| `Strategy` | Business decisions | "Target enterprise market first" |
-| `Decision` | General choices | "Approved PR #123" |
-
----
-
-## Integration
-
-### How do I connect Cursor?
-
-Add to your Cursor MCP config (`~/.config/cursor/mcp.json`):
-
-```json
-{
-  "mcpServers": {
-    "nucleus": {
-      "command": "python",
-      "args": ["-m", "mcp_server_nucleus"]
-    }
-  }
-}
-```
-
-### How do I connect Claude Desktop?
-
-Run `nucleus-init` and restart Claude Desktop. It auto-configures.
-
-Or manually add to `~/.config/Claude/claude_desktop_config.json`:
-
-```json
-{
-  "mcpServers": {
-    "nucleus": {
-      "command": "python",
-      "args": ["-m", "mcp_server_nucleus"]
-    }
-  }
-}
-```
-
-### Can I use Nucleus with multiple AI tools simultaneously?
-
-Yes! That's the whole point. Write a memory in Claude → it's instantly available in Cursor. All tools share the same `.brain/` folder.
-
----
-
-## Troubleshooting
-
-### "Module not found" error
-
-```bash
-pip uninstall nucleus-mcp
-pip install nucleus-mcp
-```
-
-### "Brain path not found"
-
-Set the environment variable:
-```bash
-export NUCLEAR_BRAIN_PATH=~/.brain
-```
-
-### Engrams not syncing between tools
-
-1. Both tools must point to the same `.brain/` path
-2. Check `NUCLEAR_BRAIN_PATH` is consistent
-3. Verify engrams were written: `ls ~/.brain/engrams/`
-
-### Tests failing with import errors
-
-This is an IDE linting issue, not a real error. Tests pass with:
-```bash
-PYTHONPATH=src pytest tests/
-```
-
----
-
-## Comparison
-
-### How is Nucleus different from ContextStream?
-
-| Aspect | Nucleus | ContextStream |
-|--------|---------|---------------|
-| Data location | 100% local | Cloud |
-| Account required | No | Yes |
-| Cross-platform | All MCP tools | Limited |
-| Price | Free (MIT) | Paid tiers |
-| Air-gap support | Yes | No |
-
-### How is Nucleus different from OpenClaw?
-
-| Aspect | Nucleus | OpenClaw |
-|--------|---------|----------|
-| Platform support | All MCP tools | Claude only |
-| Security focus | Built-in | Post-breach |
-| Stability | Production | "Hype stage" |
-| Data sovereignty | 100% local | Cloud bridge |
-
----
-
-## Contributing
-
-### How can I contribute?
-
-See [CONTRIBUTING.md](../CONTRIBUTING.md). We welcome:
-- Bug reports
-- Feature requests
-- Documentation improvements
-- Code contributions
-
-### Where do I report bugs?
-
-[GitHub Issues](https://github.com/eidetic-works/nucleus-mcp/issues)
-
----
-
-## Support
-
-- **Discord**: [Nucleus Vanguard](https://discord.gg/RJuBNNJ5MT)
-- **GitHub**: [Issues & Discussions](https://github.com/eidetic-works/nucleus-mcp)
-- **Enterprise**: [enterprise@nucleusos.dev](mailto:enterprise@nucleusos.dev)
-
----
-
-*The Sovereign Brain - Cross-platform AI memory that never leaves your machine.*

package/docs/QUICK_START.md

@@ -1,155 +0,0 @@
-# Nucleus MCP: Quick Start Guide
-
-Get cross-platform AI memory syncing in under 2 minutes.
-
----
-
-## Prerequisites
-
-- Python 3.10+
-- Claude Desktop, Cursor, or any MCP-compatible tool
-
----
-
-## Installation
-
-```bash
-pip install nucleus-mcp
-nucleus-init
-```
-
-This creates:
-- `~/.brain/` directory (your sovereign brain)
-- Auto-configures Claude Desktop if installed
-
----
-
-## Verify Installation
-
-```bash
-# Check brain health
-python -c "from mcp_server_nucleus import brain_health; print(brain_health())"
-```
-
-Expected output:
-```json
-{"status": "healthy", "version": "1.0.5", "brain_path": "/Users/you/.brain"}
-```
-
----
-
-## First Memory (Engram)
-
-Write your first cross-platform memory:
-
-```python
-from mcp_server_nucleus import brain_write_engram
-
-# Save a decision
-brain_write_engram(
-    key="tech_stack_choice",
-    value="Using FastAPI + SQLite for MVP backend",
-    context="Architecture",
-    intensity=8
-)
-```
-
-This engram is now available in **all** your MCP tools.
-
----
-
-## Query Memory
-
-Retrieve engrams by context:
-
-```python
-from mcp_server_nucleus import brain_query_engrams
-
-# Get all Architecture decisions
-engrams = brain_query_engrams(context="Architecture", min_intensity=5)
-print(engrams)
-```
-
----
-
-## Available Contexts
-
-| Context | Use For |
-|---------|---------|
-| `Feature` | Product features, implementations |
-| `Architecture` | Technical decisions, stack choices |
-| `Brand` | Messaging, positioning, identity |
-| `Strategy` | Business decisions, roadmap |
-| `Decision` | General decisions, choices made |
-
----
-
-## Connect Multiple Tools
-
-### Claude Desktop
-
-Already configured by `nucleus-init`. Restart Claude Desktop to activate.
-
-### Cursor
-
-Add to your Cursor MCP config:
-
-```json
-{
-  "mcpServers": {
-    "nucleus": {
-      "command": "python",
-      "args": ["-m", "mcp_server_nucleus"]
-    }
-  }
-}
-```
-
-### Windsurf
-
-Add to your Windsurf MCP config (same format as Cursor).
-
----
-
-## Next Steps
-
-- **[Enterprise Guide](ENTERPRISE.md)** - Air-gap deployment, compliance
-- **[Competitive Analysis](COMPETITIVE_ANALYSIS.md)** - Why Nucleus
-- **[Full API Reference](https://github.com/eidetic-works/nucleus-mcp#-complete-tool-reference)** - All 15+ tools
-
----
-
-## Troubleshooting
-
-### "brain_path not found"
-
-```bash
-# Manually set brain path
-export NUCLEAR_BRAIN_PATH=~/.brain
-```
-
-### Import errors
-
-```bash
-# Reinstall
-pip uninstall nucleus-mcp
-pip install nucleus-mcp
-```
-
-### Claude Desktop not seeing Nucleus
-
-1. Restart Claude Desktop
-2. Check `~/.config/Claude/claude_desktop_config.json` includes Nucleus
-3. Run `nucleus-init` again
-
----
-
-## Support
-
-- **Discord**: [Join Nucleus Vanguard](https://discord.gg/RJuBNNJ5MT)
-- **GitHub Issues**: [Report a bug](https://github.com/eidetic-works/nucleus-mcp/issues)
-- **Enterprise**: [enterprise@nucleusos.dev](mailto:enterprise@nucleusos.dev)
-
----
-
-*The Sovereign Brain - Cross-platform AI memory that never leaves your machine.*

package/docs/README.md

@@ -1,67 +0,0 @@
-# Nucleus MCP Documentation
-
-Welcome to the Nucleus MCP documentation. This index provides quick access to all available guides and resources.
-
----
-
-## 📚 Documentation Index
-
-### Getting Started
-
-| Document | Description |
-|----------|-------------|
-| [Quick Start](QUICK_START.md) | Install and write your first engram in 2 minutes |
-| [FAQ](FAQ.md) | Frequently asked questions |
-
-### Enterprise & Compliance
-
-| Document | Description |
-|----------|-------------|
-| [Enterprise Guide](ENTERPRISE.md) | Air-gap deployment, compliance, security architecture |
-| [Competitive Analysis](COMPETITIVE_ANALYSIS.md) | Feature comparison vs ContextStream, OpenClaw, etc. |
-
-### Community
-
-| Document | Description |
-|----------|-------------|
-| [Community FAQ](COMMUNITY_FAQ.md) | Community-contributed questions |
-| [Demo Script](DEMO_SCRIPT.md) | Video demo reference script |
-| [Social Preview](SOCIAL_PREVIEW.md) | Brand assets and social media guidelines |
-
----
-
-## 🔗 Quick Links
-
-- **Main README**: [../README.md](../README.md)
-- **GitHub**: [github.com/eidetic-works/nucleus-mcp](https://github.com/eidetic-works/nucleus-mcp)
-- **PyPI**: [pypi.org/project/nucleus-mcp](https://pypi.org/project/nucleus-mcp/)
-- **Discord**: [Nucleus Vanguard](https://discord.gg/RJuBNNJ5MT)
-- **Website**: [nucleusos.dev](https://nucleusos.dev)
-
----
-
-## 📖 Document Map
-
-```
-docs/
-├── README.md              # This index
-├── QUICK_START.md         # 2-minute getting started
-├── FAQ.md                 # Comprehensive FAQ
-├── ENTERPRISE.md          # Enterprise deployment
-├── COMPETITIVE_ANALYSIS.md # Market positioning
-├── COMMUNITY_FAQ.md       # Community questions
-├── DEMO_SCRIPT.md         # Video script
-└── SOCIAL_PREVIEW.md      # Brand assets
-```
-
----
-
-## 🆘 Need Help?
-
-- **Discord**: [Join Nucleus Vanguard](https://discord.gg/RJuBNNJ5MT)
-- **GitHub Issues**: [Report a bug](https://github.com/eidetic-works/nucleus-mcp/issues)
-- **Enterprise**: [enterprise@nucleusos.dev](mailto:enterprise@nucleusos.dev)
-
----
-
-*The Sovereign Brain - Cross-platform AI memory that never leaves your machine.*

package/examples/basic_usage.py

@@ -1,84 +0,0 @@
-"""
-Basic Usage Example for Nucleus MCP
-
-This example demonstrates how to use Nucleus MCP programmatically.
-Typically, you'd use it via an MCP client like Claude Desktop or Cursor,
-but this shows the underlying API.
-"""
-
-import os
-import tempfile
-from pathlib import Path
-
-# Set up a temporary brain for this example
-with tempfile.TemporaryDirectory() as tmpdir:
-    os.environ["NUCLEAR_BRAIN_PATH"] = tmpdir
-    
-    # Import after setting env var
-    from mcp_server_nucleus import (
-        brain_write_engram,
-        brain_query_engrams,
-        brain_get_state,
-        brain_set_state,
-        brain_identify_agent,
-        brain_sync_now,
-        brain_health,
-    )
-    
-    print("🧠 Nucleus MCP - Basic Usage Example")
-    print("=" * 50)
-    
-    # 1. Check health
-    print("\n1. Checking brain health...")
-    health = brain_health()
-    print(health)
-    
-    # 2. Identify as an agent
-    print("\n2. Registering as an agent...")
-    agent = brain_identify_agent("example_agent", "python_script")
-    print(agent)
-    
-    # 3. Store some knowledge
-    print("\n3. Storing knowledge (engrams)...")
-    engram1 = brain_write_engram(
-        content="We decided to use PostgreSQL for the user database",
-        category="decision",
-        tags=["database", "architecture"]
-    )
-    print(engram1)
-    
-    engram2 = brain_write_engram(
-        content="The API should use REST with JSON responses",
-        category="decision",
-        tags=["api", "architecture"]
-    )
-    print(engram2)
-    
-    # 4. Query knowledge
-    print("\n4. Querying knowledge...")
-    results = brain_query_engrams(query="database")
-    print(results)
-    
-    # 5. Set some state
-    print("\n5. Setting project state...")
-    state = brain_set_state("current_sprint", "MVP Genesis")
-    print(state)
-    
-    state = brain_set_state("team_size", "1")
-    print(state)
-    
-    # 6. Get state
-    print("\n6. Getting current state...")
-    current_state = brain_get_state()
-    print(current_state)
-    
-    # 7. Sync
-    print("\n7. Syncing brain...")
-    sync = brain_sync_now()
-    print(sync)
-    
-    print("\n" + "=" * 50)
-    print("✅ Example complete!")
-    print(f"Brain location: {tmpdir}")
-    print("\nIn real usage, other AI tools (Claude, Cursor, Windsurf)")
-    print("would be able to access this same brain and share context.")

package/package.json.real

@@ -1,24 +0,0 @@
-{
-    "name": "nucleus-mcp",
-    "version": "1.0.7",
-    "description": "The Universal Brain for AI Agents - Cross-platform memory sync for Cursor, Claude, Windsurf",
-    "main": "index.js",
-    "module": "index.js",
-    "bin": {
-        "nucleus-mcp": "./index.js",
-        "nucleus-init": "./index.js"
-    },
-    "scripts": {
-        "test": "echo \"Error: no test specified\" && exit 1"
-    },
-    "keywords": [
-        "mcp",
-        "ai",
-        "agents",
-        "memory",
-        "nucleus"
-    ],
-    "author": "Nucleus Team",
-    "license": "MIT",
-    "dependencies": {}
-}

package/pyproject.toml

@@ -1,50 +0,0 @@
-[build-system]
-requires = ["hatchling"]
-build-backend = "hatchling.build"
-
-[project]
-name = "nucleus-mcp"
-version = "1.0.5"
-description = "The Sovereign Agent Control Plane with Governance & Engrams"
-readme = "README.md"
-authors = [
-    { name = "Nucleus Team", email = "hello@nucleusos.dev" }
-]
-urls = { Homepage = "https://github.com/eidetic-works/nucleus-mcp", Repository = "https://github.com/eidetic-works/nucleus-mcp" }
-requires-python = ">=3.10"
-dependencies = [
-    "pydantic",
-    "watchdog>=3.0.0",
-    "google-cloud-firestore>=2.11.0",
-    "duckduckgo-search>=4.0.0",
-    "beautifulsoup4>=4.12.0",
-    "nest_asyncio",
-    "cryptography>=41.0.0"
-]
-
-[project.optional-dependencies]
-full = [
-    "fastmcp",
-    "google-genai"
-]
-dev = [
-    "pytest>=7.0",
-    "pytest-cov",
-    "ruff"
-]
-
-[project.scripts]
-nucleus-mcp = "mcp_server_nucleus:main"
-nucleus-init = "mcp_server_nucleus.cli:main"
-
-[tool.hatch.build.targets.wheel]
-packages = ["src/mcp_server_nucleus"]
-
-[tool.pytest.ini_options]
-testpaths = ["tests"]
-pythonpath = ["src"]
-
-[tool.ruff]
-line-length = 100
-target-version = "py310"
-

package/registry-server.json

@@ -1,20 +0,0 @@
-{
-    "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
-    "name": "io.github.eidetic-works/nucleus",
-    "description": "Sovereign agent control plane with task ledger, hypervisor security, and long-term memory.",
-    "repository": {
-        "url": "https://github.com/eidetic-works/nucleus-mcp",
-        "source": "github"
-    },
-    "version": "1.0.2",
-    "packages": [
-        {
-            "registryType": "npm",
-            "identifier": "nucleus-mcp",
-            "version": "1.0.2",
-            "transport": {
-                "type": "stdio"
-            }
-        }
-    ]
-}