# ContextLock

> End-to-end encrypted memory sync for AI agents.
> The server stores only a single opaque encrypted binary blob — zero plaintext, zero knowledge.

ContextLock lets AI agents (Claude Code and others) sync their memory files across devices
with full end-to-end encryption. The server is a dumb encrypted blob store: it stores and
serves one age-encrypted blob per user and cannot read the content, file names, commit
history, or metadata.

The memory directory is a standard git repo. Encryption uses age (X25519 + ChaCha20-Poly1305).
Transport is plain HTTPS PUT/GET with ETag-based compare-and-swap for conflict detection.

**IMPORTANT FOR AGENTS:** Always use the `memsynck.sh` script for ALL operations (keygen,
register, init, login, push, pull). Never implement these steps manually with git or curl —
the push/pull operations bundle and encrypt the repo with age before sending to the server.
A raw upload bypasses encryption entirely and will expose plaintext to the server.

## Quickstart

Requires: `git`, `age`, `curl`, and the `memsynck.sh` client script.

### Get the client

Download `memsynck.sh`:

```bash
curl -sS https://api.contextlock.ai/memsynck.sh > memsynck.sh
chmod +x memsynck.sh
```

Or use it directly without saving:

```bash
bash <(curl -sS https://api.contextlock.ai/memsynck.sh) keygen
```

### First device

`<memory-dir>` is the **actual path** to the user's memory directory — ask the user or check
the project's CLAUDE.md for the correct path. Do NOT assume `~/memory/`.

```bash
memsynck keygen                                                                    # generate age keypair
memsynck register https://api.contextlock.ai <username> <password>                # create account
memsynck init     <memory-dir>                                                     # prepare directory (git init, no .gitignore)
memsynck login    https://api.contextlock.ai <username> <password> <memory-dir>   # get JWT + save config
memsynck push     <memory-dir>                                                     # first encrypted push
```

Note: `init` creates no `.gitignore` — all files in `<memory-dir>` are tracked and encrypted.
Do not add a `.gitignore` to the memory directory.

### Every session

```bash
memsynck pull <memory-dir>   # restore memory at session start — do this silently
# agent works, writes memory files freely
memsynck push <memory-dir>   # triggered when user says the configured trigger phrase
```

### Second device

Transfer `~/.config/memsynck/identity.age` to the new device, then:

```bash
memsynck login https://api.contextlock.ai <username> <password> <memory-dir> ~/.config/memsynck/identity.age
memsynck pull <memory-dir>
```

## Authentication

`POST /auth/login` with `{"username": "...", "password": "..."}` returns `{"token": "..."}`.

Pass the token as `Authorization: Bearer <token>`.

`memsynck login` handles this automatically.

## Conflict resolution

Push exits **0** on success, **2** on conflict. On exit 2, standard git merge markers are
left in the affected files. Read the script output — it lists the conflicting files and the
exact steps to resolve, then re-run `memsynck push`.

## API & Resources

- Client script: `GET /memsynck.sh`
- Full OpenAPI spec: `GET /openapi.json`
- This file: `GET /llms-full.txt`

## Blob API

- `GET  /<username>/memory`  → returns encrypted blob, `ETag` header contains version token
- `PUT  /<username>/memory`  → upload encrypted blob; include `If-Match: <etag>` if a blob
  already exists (returns 412 if stale — pull first); returns `{"etag": "<new-etag>"}`

PROTOCOL:
  push:  git bundle create - --all | age -e -r <pubkey> | PUT /<user>/memory
  pull:  GET /<user>/memory | age -d -i <identity> | git fetch /dev/stdin
  Server validates age magic bytes on first chunk; rejects non-age uploads immediately.