# Novyx MCP - Desktop Extension

Desktop Extension (`.mcpb`) for [Claude Desktop](https://claude.ai/download).
This repo is the one-click installer shell for the Python
[`novyx-mcp`](https://pypi.org/project/novyx-mcp/) engine.

Current desktop extension: `1.0.6`
Current MCP engine target: `novyx-mcp` `2.8.0`

## Features

- **Reviewable Memory** - Draft, review, diff, merge, or reject agent memory
  before it becomes permanent.
- **Governed Actions** - Submit, approve, deny, and explain agent actions when
  connected to Novyx Cloud.
- **Time-Travel Rollback** - Preview and restore memory to a known-good point.
- **Audit Trails** - Inspect cryptographic proof of memory operations.
- **Knowledge Graph** - Link memories and query subject-predicate-object
  triples.
- **Context Spaces** - Keep project and team memory separated.
- **Local-First** - Works instantly with SQLite and no API key.
- **Cloud Upgrade** - Optional hosted governance, approvals, replay, Runtime
  v2, threat intelligence, and team workflows.

## Installation

**From the Anthropic Directory (recommended):**

Install directly from Claude Desktop -> Settings -> Extensions.

**Manual install:**

1. Download the latest `.mcpb` file from [Releases](https://github.com/novyxlabs/novyx-mcp-desktop/releases)
2. Double-click the file, or drag it into Claude Desktop

**Prerequisites:** Python 3.10+ must be installed. The extension first tries
`uvx --upgrade novyx-mcp`, then falls back to `python3 -m novyx_mcp`,
`python -m novyx_mcp`, and finally the `novyx-mcp` executable.

## Configuration

**No configuration required for local mode.** The extension works out of the
box with a local SQLite database.

**Optional - Cloud mode:**

When prompted during installation, enter your Novyx API key. Get a free key at
[novyxlabs.com](https://novyxlabs.com) (5,000 memories, no credit card).

Cloud mode enables:
- Cross-device memory sync
- Hosted governance and approval workflows
- Runtime v2 agents, missions, capabilities, checkpoints, and interventions
- Replay, cortex, and threat-intelligence workflows
- Team spaces when hosted sharing is available

`share_space` is currently visible but disabled in `novyx-mcp` 2.8.0 until
hosted invitation redemption is available. It returns a clear local-only
response instead of issuing unusable tokens.

## What To Try First

Use the desktop extension when Claude needs reviewable memory instead of
untracked context:

```text
draft_memory(
  observation="Deploys fail if REDIS_URL is unset in staging",
  tags=["ops", "staging"],
  importance=8,
  branch_id="staging-fixes"
)

memory_branch("staging-fixes")
draft_diff("drf_abc123")
merge_branch("staging-fixes")
```

That flow keeps memory changes inspectable before they become permanent.

## Usage Examples

### Example 1: Store and recall memories

**User prompt:**
> Remember that the project deadline is March 15th and we're using React with TypeScript.

**What happens:** Claude calls the `remember` tool to store tagged memories.
Later:

> What tech stack are we using for this project?

**What happens:** Claude calls `recall` with a semantic search, finds the stored
memory about React + TypeScript, and answers accurately.

### Example 2: Roll back a mistake

**User prompt:**
> I accidentally told you the deadline was March 15th - it's actually April 1st. Roll back the wrong memory and fix it.

**What happens:** Claude calls `rollback_preview` and `rollback` to undo the
incorrect memory, then `remember` to store the corrected date. The `audit`
trail shows the full history: original store -> rollback -> corrected store.

### Example 3: Build a knowledge graph

**User prompt:**
> Track these relationships: Alice manages the frontend team, Bob manages the backend team, and both teams report to Carol.

**What happens:** Claude calls `add_triple` to create knowledge graph entries:
- `Alice -> manages -> frontend team`
- `Bob -> manages -> backend team`
- `frontend team, backend team -> reports_to -> Carol`

Later, asking "Who does the frontend team report to?" triggers a
`query_triples` call that returns the answer.

### Example 4: Isolated project contexts

**User prompt:**
> Create a separate memory space for my side project so it doesn't mix with work memories.

**What happens:** Claude calls `create_space` to create an isolated context.
Memories stored in that space are scoped and do not appear in general searches.

## Privacy Policy

Novyx MCP operates in two modes:

**Local mode (default):** All data is stored locally in a SQLite database at
`~/.novyx/local.db`. No data is sent to any external server. No analytics or
telemetry.

**Cloud mode (opt-in):** When you provide an API key, memories are sent to the
Novyx API (`novyx-ram-api.fly.dev`) for storage and sync. Data is encrypted in
transit (TLS) and at rest. We do not share your data with third parties. See
our full privacy policy at [novyxlabs.com/privacy](https://novyxlabs.com/privacy).

You can switch between modes at any time by adding or removing your API key.

**Data retention:** Local data persists until you delete it. Cloud data is
retained until you delete it or close your account. Audit trails are immutable
by design.

For privacy questions, contact blake@novyxlabs.com.

## Support

- **Issues:** [github.com/novyxlabs/novyx-mcp-desktop/issues](https://github.com/novyxlabs/novyx-mcp-desktop/issues)
- **Documentation:** [docs.novyxlabs.com](https://docs.novyxlabs.com)
- **Email:** blake@novyxlabs.com

## How It Works

This Desktop Extension is a thin Node.js wrapper that spawns the Python
`novyx-mcp` server as a child process. The Node.js layer handles process
lifecycle; the Python server handles all MCP logic.

Launch order:
1. `uvx --upgrade novyx-mcp` (fastest; no install needed)
2. `python3 -m novyx_mcp` (if pip installed)
3. `python -m novyx_mcp`
4. `novyx-mcp` (if pipx installed)

## Release

Build the desktop extension bundle:

```bash
npm run validate
npm run package
```

The package script writes `dist/novyx-mcp-desktop-<version>.mcpb`. The bundle
contains `manifest.json`, `server/index.js`, icons, license, README, and
package metadata with `manifest.json` at the archive root.

## License

MIT