Storage Architecture

Your context is your life data. It can't live primarily on someone else's server. PCF storage is local-first, encrypted with keys only you hold, and optionally syncable across your devices.

Local-First Design

The vault is functional without any network connection. Sync is additive, not required. Your context works offline, forever.

Recommended

SQLite + Encryption Layer

Single file, portable, queryable, well-understood, excellent tooling. Wrap with libsodium or similar for at-rest encryption.

  • Works on all platforms (iOS, Android, desktop, web)
  • Queryable with standard SQL
  • Single file = simple backup
  • Mature ecosystem
Alternative

Directory of JSON + Git

Human-readable, version controlled, diffable. Encryption via git-crypt or similar.

  • Human-auditable files
  • Git-native version history
  • Easy merge/conflict resolution
  • Querying is harder
Advanced

Embedded Graph DB

Better for complex relational queries. More implementation complexity.

  • Native graph traversal
  • Pattern matching queries
  • Higher memory usage
  • Less portable

Storage Layers

Application Layer
PCF API (read, write, query)
Encryption Layer (libsodium)
Storage Engine (SQLite/JSON/Graph)
Local Filesystem

Encryption Model

All context is encrypted at rest using keys derived from your credentials. Even if someone gets the file, they can't read it without your keys.

Key Derivation

1

User Password

You provide a password (or passphrase, or biometric)

2

Argon2id KDF

Password-based key derivation with high memory cost

3

Master Key

256-bit key used to derive per-record keys

At-Rest Encryption

  • Algorithm: XChaCha20-Poly1305 (AEAD)
  • Key rotation: Optional, per-record keys derived from master
  • Nonce: Random per-encryption, stored with ciphertext
  • Authentication: Poly1305 MAC prevents tampering

Key Hierarchy

Master Key (derived from password)
├── Content Key (encrypts entity data)
├── Index Key (encrypts search indices)
└── Sync Key (encrypts sync bundles)

Key Recovery

  • Recovery phrase (BIP-39 style) for master key backup
  • Optional key escrow to trusted contacts
  • No recovery if all keys lost — by design

We cannot recover your data.

Helaix never has access to your encryption keys. If you lose your password and recovery phrase, your data is permanently inaccessible. This is a feature, not a limitation.

Sync Protocol

Optional sync between devices. All sync traffic is encrypted end-to-end — the sync server only sees opaque blobs it cannot read.

CRDT-Based Merge

PCF uses CRDTs (Conflict-free Replicated Data Types) to handle concurrent edits across devices without conflicts.

LWW-Register

Last-writer-wins for simple fields (title, description)

G-Set

Grow-only set for entities (entities can be added, tombstoned)

OR-Set

Observed-remove set for relations (add + remove without conflicts)

Vector Clock

Causality tracking for ordering operations

Sync Backends

Helaix Sync (Default)

Hosted sync service. Encrypted blobs only. We see blob sizes and sync frequency, never content.

Zero-knowledge

Self-Hosted

Run sync server on your infrastructure. Same protocol, you control the storage.

Full control

Cloud Storage

Sync to S3, GCS, or any object storage. Encrypted blobs uploaded directly.

Bring your own

Peer-to-Peer

Direct device-to-device sync when on same network. No server required.

Serverless

Protocol Overview

  1. Local change — Entity created/modified, assigned vector clock timestamp
  2. Bundle creation — Changes since last sync bundled, encrypted with sync key
  3. Upload — Encrypted bundle pushed to sync backend
  4. Notification — Other devices notified of new bundle
  5. Download — Devices fetch and decrypt bundle
  6. Merge — CRDT rules applied, local state updated
  7. Acknowledgment — Sync state updated, bundle marked processed

Access Control

Selective disclosure is core to PCF. You decide what each AI tool sees, at what granularity, for what purpose.

Scoped Access Tokens

When an AI tool requests context, you generate a scoped token that specifies exactly what it can access.

AccessToken {
  id: uuid
  created: timestamp
  expires: timestamp

  // What can be accessed
  entity_types: ["Goal", "Project", "Task"]
  domains: ["work", "learning"]
  time_range: [last_30_days, now]

  // Access level
  granularity: "summary" | "detail" | "full"
  can_write: false

  // Purpose tracking
  purpose: "coding_assistant"
  tool_id: "claude_code"
}

Example Access Patterns

Claude Code Work context only
  • Entity types: Project, Task, Skill
  • Domains: work, learning
  • Granularity: detail
  • Time range: active projects only
Health Assistant Health context only
  • Entity types: Goal, State, Event
  • Domains: health
  • Granularity: full
  • Time range: last 90 days
General Assistant Summary only
  • Entity types: Goal, Value
  • Domains: all
  • Granularity: summary (no details)
  • Time range: current only

Audit Trail

Every access is logged. You can see exactly what was shared with whom and when.

AccessLog {
  timestamp: "2026-01-16T14:30:00Z"
  token_id: "tok_abc123"
  tool_id: "claude_code"
  operation: "read"
  entities_accessed: 12
  query: "active projects in work domain"
}

Audit logs are stored locally, encrypted, and never shared. They're for your visibility into what AI tools accessed.

Implementation Reference

Recommended stack for building a PCF-compliant implementation.

Storage

better-sqlite3 Node.js
sql.js Browser/WASM
SQLCipher Mobile (native encryption)

Encryption

libsodium Recommended (XChaCha20-Poly1305)
@noble/ciphers Pure JS alternative

CRDTs

yjs Full-featured CRDT library
automerge Alternative with different tradeoffs

AI Integration

MCP Server Model Context Protocol for Claude
REST API For tools without MCP support

Key Considerations

  • Mobile storage limits: iOS has strict limits on local storage. Consider compaction strategies.
  • Key management: Securely storing the master key is platform-specific. Use Keychain (iOS), Keystore (Android), or OS-level secure storage.
  • Background sync: Mobile platforms restrict background network activity. Design for infrequent, batched syncs.
  • Migration strategy: Schema evolution needs forward and backward compatibility. Version all stored data.

Ready to build?

You've covered the PCF specification — the ontology, schema, and storage architecture. Now you can implement a compliant personal context vault.