A personal knowledge base for saving and searching web articles. All intelligence — content fetching, text extraction, chunking, embedding, searching, encryption — runs on your device. The server is an optional encrypted blob store for backup and multi-device sync.
- Save a URL (via chat agent, share sheet, or CLI)
- The client fetches, chunks, and embeds the article on-device
- Everything is encrypted before leaving the device
- Search your knowledge base with natural language — locally, instantly
npm install -g @de-otio/chaoskb-clientThat's it. On first launch, ChaosKB detects your SSH key, enables sync automatically, and encrypts your data with your public key. No setup commands, no accounts, no configuration.
- Desktop —
@de-otio/chaoskb-client, an npm package that runs as an MCP server for any compatible chat agent (Claude Desktop, Claude Code, Cursor, VS Code, etc.) - Mobile (future) — Flutter app for iOS and Android
| Property | Value |
|---|---|
| Privacy | Server never sees plaintext — opaque ciphertext only |
| Offline | Fully functional without a server |
| Search | On-device embedding + brute-force cosine similarity (<50ms) |
| Encryption | XChaCha20-Poly1305, HKDF-SHA256, Argon2id |
| Server cost | ~$0.25/mo (DynamoDB + Lambda), or $0 in local-only mode |
| Tier | Key management | Recovery |
|---|---|---|
| Standard (default) | Your SSH key | Same SSH key on new device restores everything |
| Enhanced (deprecated) | 24-word recovery key + SSH key | Recovery key OR SSH private key |
| Maximum | Passphrase you choose | Re-enter passphrase on new device |
All tiers are end-to-end encrypted — the server stores only ciphertext it cannot decrypt. Lose your key material (SSH key, recovery words, or passphrase depending on tier), and your data is gone. No backdoor, no server-side key escrow. Enhanced is deprecated for new installations; use Maximum for stronger protection.
Deploy your own backend with a single command:
npx chaoskb-deploy --ssh-pubkey ~/.ssh/id_ed25519.pub
# or, fetch the public key from GitHub:
npx chaoskb-deploy --github <username>This creates a Lambda Function URL + DynamoDB table in your AWS account. See self-hosting docs.
User guide (doc/user/)
- Getting started — install, first save, first search
- Chat agent setup — register with Claude Desktop, Cursor, VS Code, etc.
- MCP tools reference — what you can ask your agent to do
- Security tiers — choosing, upgrading, recovery
- Managing your library — search, delete, cleanup, storage
- Project knowledge bases — isolated, scoped KBs for specific work
- Data portability — export, import, migrate
- Troubleshooting — common issues and fixes
Admin guide (doc/admin/)
- Deploy — deploy a self-hosted backend
- Configure — CDK customizations, client config
- Operations — monitoring, cost, API key rotation, backups
- Tear down — remove the backend safely
Design (doc/design/)
- Overview — architecture, what the server knows, key properties
- Cryptographic design — security tiers, key hierarchy, encryption scheme, key rotation
- Envelope specification — wire format, algorithms, test vectors
- Client architecture — on-device embedding, local search, sync protocol
- Server architecture — minimal encrypted storage API
- MCP integration — how chat agents interact with the knowledge base
- Threat model — what's protected, what's not, residual risks
- Tier upgrade protocol — cryptographic protocol for changing tiers
- Portability — data export, instance migration, shutdown guarantee
- Self-hosting — deploy your own backend, client configuration
See SECURITY.md for the vulnerability disclosure policy and cryptographic dependencies.