contextmate

v0.4.29

Published

8 days ago

Zero-knowledge encrypted sync for AI agent context

0High
0Medium
0Low

alexfurm

ai agents sync encryption zero-knowledge mcp cli context

ContextMate

Zero-knowledge encrypted sync for AI agent context.

Dropbox for your AI brain. Memories, skills, and rules -- encrypted and auto-synced across every agent and device.

Quick Install

curl -fsSL https://raw.githubusercontent.com/contextmate/contextmate/main/install.sh | bash

What It Does

Your AI agents (Claude Code, Cursor, OpenClaw) store knowledge in markdown files -- memories, skills, rules, and identity. These files live on one machine in one agent's directory.

ContextMate syncs them everywhere:

Cross-device: Your skills and memories follow you to every machine.
Cross-agent: Knowledge written in Claude Code flows to OpenClaw and back.
Zero-knowledge encryption: Your passphrase never leaves your device. The server stores only encrypted blobs.

Quick Start

One command does everything:

contextmate setup

This guided setup will:

Create your account (or log into an existing one)
Auto-detect Claude Code and OpenClaw
Import your skills, rules, and memories
Ask which directories to scan for project skills
Sync all files to the cloud
Open the web dashboard at app.contextmate.dev
Start the sync daemon

That's it. Your AI context is now encrypted, synced, and accessible from any device.

Web Dashboard

Manage your vault, devices, and API keys from app.contextmate.dev. View synced files, edit per-device scan paths, and create API keys -- all from the browser.

Multi-device

On a second machine, run the same command and choose "Log into existing account":

contextmate setup
# Choose: 2. Log into existing account
# Enter your User ID and passphrase

CLI Reference

| Command | Description | |---------|-------------| | contextmate setup | Complete guided setup -- account, adapters, sync, and dashboard | | contextmate status | Show sync state, adapters, daemon, conflicts | | contextmate log | Show recent sync activity (uploads, downloads, errors) | | contextmate files | List all tracked files with sync state | | contextmate files reset-cursor | Force full re-reconciliation on next sync | | contextmate files clear-tombstones | Clear deletion markers blocking re-download | | contextmate daemon install | Install persistent sync service (recommended) | | contextmate daemon status | Check if daemon is running | | contextmate daemon stop | Stop the sync daemon | | contextmate mcp setup | Auto-configure MCP for Claude, Cursor, Windsurf, ChatGPT | | contextmate reset | Remove all ContextMate data from this machine |

Most users only need contextmate setup. The other commands are for troubleshooting.

Adapter Configuration

After running contextmate setup, you can customize which files each adapter syncs by editing ~/.contextmate/config.toml.

OpenClaw Adapter

By default, the OpenClaw adapter syncs:

Top-level workspace files: MEMORY.md, IDENTITY.md, USER.md, SOUL.md
Memory files: memory/*.md
Skill files: skills/*/SKILL.md

To sync additional files (e.g., playbooks, process docs, config files), use extraFiles or extraGlobs in the config:

[adapters.openclaw]
enabled = true
workspacePath = "/Users/you/.openclaw/workspace"

# Sync specific files (paths are RELATIVE to workspacePath)
extraFiles = [
  "playbooks/bliss.md",
  "playbooks/system.md",
  "processes/sourcing.md",
  "AGENTS.md",
  "TOOLS.md",
  "HEARTBEAT.md"
]

# Or use glob patterns (also relative to workspacePath)
extraGlobs = [
  "playbooks/*.md",
  "processes/*.md"
]

Note: All paths in extraFiles and extraGlobs are resolved relative to workspacePath, not as absolute paths.

After editing the config, re-import and restart the daemon:

contextmate adapter openclaw init
contextmate daemon stop
contextmate daemon start

Verify the new files are tracked:

contextmate files

Self-Hosting

You can run your own ContextMate server instead of using the hosted service.

Deploy to Railway

Railway will provision a server with persistent storage. The JWT_SECRET is auto-generated on first start.

Docker Compose

git clone https://github.com/contextmate/contextmate.git
cd contextmate
docker compose up -d

The server stores data in a Docker volume at /app/data. To customize, copy .env.example to .env and edit as needed.

Connect the CLI

During contextmate setup, enter your server URL when prompted:

Server URL (Enter for hosted service): https://your-server.example.com

Or edit ~/.contextmate/config.toml directly:

[server]
url = "https://your-server.example.com"

Then restart the daemon: contextmate daemon stop && contextmate daemon start

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | JWT_SECRET | auto-generated | JWT signing secret. Set explicitly for multi-instance deployments. | | PORT | 3000 | Server port. | | INVITE_CODE | (none) | If set, new users must provide this code to register. Leave unset for open registration. |

Invite Codes

By default, anyone who knows your server URL can create an account. To restrict registration, set an INVITE_CODE on the server:

# Docker Compose: add to .env
INVITE_CODE=my-secret-code

# Railway: set in service variables

When a user runs contextmate setup, they'll be prompted for the invite code. Existing accounts are not affected — the code is only required for new registrations.

Architecture

Passphrase --> Argon2id --> Master Key --> HKDF branches
                             |
                             +-- vault key (per-file AES-256-GCM encryption)
                             +-- auth key  (server authentication)
                             +-- sharing key (future sharing features)

All encryption happens on your device with AES-256-GCM.
The server only ever sees encrypted blobs.
Keys are derived using Argon2id (t=3, m=64MB, p=4) and HKDF-SHA256.

Read the full security model at contextmate.dev/security.

Connect to More AI Apps

After setup, connect ContextMate's MCP server to Cursor, Windsurf, Claude Desktop, or ChatGPT:

contextmate mcp setup

This auto-detects installed apps and writes their MCP configs. Your AI apps get 6 tools: search, read, and write your memories and skills.

Supported Agents

| Agent | Status | |-------|--------| | Claude Code | Supported (adapter + MCP) | | Claude Desktop | Supported (MCP) | | OpenClaw | Supported (adapter) | | Cursor | Supported (MCP) | | Windsurf | Supported (MCP) | | ChatGPT Desktop | Supported (MCP) |

Development

Prerequisites

Node.js 20+

Setup

# Clone the repo
git clone https://github.com/contextmate/contextmate.git
cd contextmate

# CLI (root)
npm install
npm run build

# Server
cd server
npm install

# Web dashboard
cd web
npm install

# Marketing site
cd www
npm install

Run Tests

npx vitest run

Project Structure

src/                  # CLI client
  bin/                #   Entry point
  cli/                #   Commands (setup, init, status, adapter, daemon, mcp, files, log, reset)
  crypto/             #   Encryption (AES-256-GCM, Argon2id, HKDF, BLAKE3)
  sync/               #   Sync engine (watcher, state, WebSocket)
  adapters/           #   Agent adapters (Claude Code, OpenClaw)
  mcp/                #   Local MCP server (BM25 search)
server/               # Cloud API (Hono, SQLite, WebSocket)
web/                  # Web dashboard (React, Vite, Web Crypto API)
www/                  # Marketing site (Astro 5, Tailwind CSS v4)
tests/                # Test suites (Vitest)

Security

ContextMate is built on a zero-knowledge architecture. Your passphrase is never transmitted, and the server cannot decrypt your data. All cryptographic operations use audited libraries (@noble/ciphers, @noble/hashes).

For details, see contextmate.dev/security.