Encrypted, ephemeral, private memos on atproto
graham.systems
1# Cistern
2
3Cistern is a private, end-to-end encrypted quick-capture system built on AT
4Protocol. Memos are encrypted using post-quantum cryptography and stored
5temporarily in your Personal Data Server (PDS), then automatically retrieved and
6deleted after consumption.
7
8The system bridges the gap between where ideas are captured and where they are
9stored long-term. Create an encrypted memo on your phone, and it automatically
10appears in your desktop application, decrypted and ready to use.
11
12## Architecture
13
14Cistern is a Deno monorepo consisting of six packages:
15
16### `@cistern/crypto`
17
18Core cryptographic operations using post-quantum algorithms. Implements X-Wing
19key encapsulation with XChaCha20-Poly1305 authenticated encryption and SHA3-512
20integrity verification. Handles keypair generation, encryption, and decryption.
21
22### `@cistern/lexicon`
23
24AT Protocol schema definitions for Cistern record types. Defines
25`app.cistern.pubkey` (public key records) and `app.cistern.memo` (encrypted memo
26records). Includes code generation from JSON schemas.
27
28### `@cistern/shared`
29
30Common utilities and authentication logic. Handles DID resolution via Slingshot
31service and creates authenticated RPC clients using app passwords.
32
33### `@cistern/producer`
34
35Creates and encrypts memos for storage. Manages public key selection, encrypts
36plaintext content, and uploads encrypted memos to the PDS as AT Protocol
37records.
38
39### `@cistern/consumer`
40
41Retrieves, decrypts, and deletes memos. Generates keypairs, manages private keys
42locally, retrieves memos via polling or real-time streaming (Jetstream), and
43handles memo deletion after consumption.
44
45### `@cistern/mcp`
46
47Model Context Protocol server that exposes Cistern as MCP tools for AI
48assistants. Supports stdio transport for local integrations (Claude Desktop) and
49HTTP transport for remote deployments. Automatically generates and persists
50keypairs in Deno KV.
51
52## Security Model
53
54Private keys never leave the consumer device. Public keys are stored in the PDS
55as records, while private keys remain off-protocol. Only the holder of the
56matching private key can decrypt memos encrypted with the corresponding public
57key.
58
59## Quick Start
60
61### Using the MCP Server with Claude Desktop
62
631. Generate an [app password](https://bsky.app/settings/app-passwords) for your Bluesky account
642. Add to Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):
65
66```json
67{
68 "mcpServers": {
69 "cistern": {
70 "command": "deno",
71 "args": ["task", "--cwd", "/path/to/cistern/packages/mcp", "stdio"],
72 "env": {
73 "CISTERN_MCP_HANDLE": "yourname.bsky.social",
74 "CISTERN_MCP_APP_PASSWORD": "xxxx-xxxx-xxxx-xxxx"
75 }
76 }
77 }
78}
79```
80
813. Restart Claude Desktop
824. Create memos using the Cistern Producer from any device
835. Ask Claude to retrieve and process your memos
84
85See [`packages/mcp/README.md`](./packages/mcp/README.md) for detailed usage.
86
87## Testing
88
89Run all unit tests:
90
91```bash
92deno test --allow-env
93```
94
95Run end-to-end tests (requires AT Protocol credentials):
96
97```bash
98CISTERN_HANDLE="your.bsky.social" \
99CISTERN_APP_PASSWORD="xxxx-xxxx-xxxx-xxxx" \
100deno test --allow-env --allow-net e2e.test.ts
101```