# CloudGentic Project Sync

**No LLM. No API keys. No vector database. One SQLite file on your server, and every AI you use picks up where the last one left off.**

A self-hosted Remote MCP server for cross-model session handoff. Start a project in ChatGPT, continue in Claude, finish anywhere: one shared project log, files with version history, and full-text search, all on hardware you control.

> There are plenty of AI "memory" servers. This is not a memory database. It is a handoff log: each session ends with a summary and next steps, so the next AI (any AI) starts with the state of the project instead of six months of transcript.

## Quick start (Docker)

```bash
git clone https://github.com/cloudgentic/project-sync && cd project-sync
docker compose up -d
docker compose exec sync node dist/cli.js token create chatgpt
# copy the token: it is shown exactly once
```

Put it behind HTTPS (required before exposing to the internet). Minimal Caddy example:

```
mcp.yourdomain.com {
    reverse_proxy 127.0.0.1:3210
}
```

Note: the compose file publishes host port **3210** (container port 3000) to stay clear of the common dev-server port. Change the mapping in docker-compose.yml if you prefer another port; behind Traefik or another container-aware proxy, drop the ports section and route to the container directly.

## Connect your AI clients (one command)

On your PC, not the server:

```bash
npx @cloudgentic/project-sync setup
```

A local page opens (or add `--cli` for the terminal). Enter your server URL and the admin key the server printed at first start, pick a client, press Connect. The assistant mints a token, **appends** `project-sync` to your client config (your other MCP servers are never touched; a backup is saved first), restarts the client, and verifies the connection with a real handshake. Built screen-reader-first: every step is announced, nothing needs a mouse.

Works today with Claude Desktop (Windows, macOS, Linux) and Claude Code. Claude web/mobile and ChatGPT custom connectors need OAuth, arriving in a later release. Manage tokens later with `npx @cloudgentic/project-sync setup manage --server <url> --admin-key <key>`.

Prefer to do it by hand? See docs/ for the manual config blocks and the paste-once instructions that automate the session ritual.

## The ritual

- **Session start:** "Load project client-alpha." The AI reads the log and briefs you.
- **Session end:** "Wrap up and log it." The AI writes the summary and next steps.
- That's the product.

## Tools

read_project_log, append_project_log, save_project_file, list_project_files, read_project_file, search_project, get_recent_activity, list_projects. Plus two MCP prompts: start_session, end_session.

## CLI (on the server)

```
node dist/cli.js admin rotate                       # new admin key, old one revoked
node dist/cli.js token create|list|revoke <label>
node dist/cli.js export <slug> [dir]     # markdown bundle
node dist/cli.js export --all [dir]
```

## Security model

Tokens are generated (never defaulted), sha256-hashed at rest, revocable instantly, max 5 active. The admin key (also hashed, rotatable) can mint and revoke tokens but cannot read or write project data. Set `ADMIN_API_ENABLED=false` for CLI-only token management. All identifiers are allowlist-validated. All data lives in SQLite: no request input ever touches a filesystem path. Non-root container. 60 req/min per token. Activity log keeps who-did-what for 90 days, never content.

## Bare-metal install (Debian/Ubuntu)

```bash
apt install -y build-essential python3 git curl   # better-sqlite3 compiles a native module
# install Node 22, then:
git clone https://github.com/cloudgentic/project-sync /opt/project-sync && cd /opt/project-sync
npm ci && npx tsc
useradd -r -m -s /usr/sbin/nologin projectsync    # "sync" is a reserved Debian user; do not use it
```
Run as a systemd service with `User=projectsync`, `DB_PATH=/var/lib/project-sync/project-sync.db`, `ExecStart=/usr/bin/node dist/server.js`. The admin key prints once in `journalctl -u project-sync` on first start.

## Dev

```
npm install
npm test      # 19 tests
npm run dev
```

MIT. Want this hosted, multi-project, with a web UI? That's [CloudGentic Workspace](https://cloudgenticai.com).