Architecture

Architecture

Frameshift is a Rust workspace of 25 crates organized in layers. Each layer has a clear role, and crates within a layer depend only on lower layers.

Layer diagram

                          ┌─────────────────┐
                          │  frameshift-cli  │  (binary)
                          │  frameshift-mcp  │  (binary)
                          │  frameshift-seed │  (binary)
                          └────────┬────────┘
                                   │
              ┌────────────────────┼────────────────────┐
              │                    │                     │
     ┌────────▼────────┐  ┌───────▼────────┐   ┌───────▼────────┐
     │ frameshift-daemon│  │frameshift-server│  │ frameshift-     │
     │ (background IPC) │  │ (HTTP API)     │   │ runtime         │
     └────────┬────────┘  └───────┬────────┘   └───────┬────────┘
              │                    │                     │
    ┌─────────┴──────────┐  ┌─────┴──────────┐  ┌──────┴──────────┐
    │frameshift-          │  │frameshift-      │  │frameshift-vault │
    │orchestrator         │  │catalog-postgres │  │frameshift-vault-│
    │(automate mode)      │  │frameshift-      │  │local            │
    │                     │  │objects-fs       │  │frameshift-      │
    │                     │  │frameshift-      │  │template         │
    │                     │  │objects-r2       │  │frameshift-memory│
    └─────────┬──────────┘  └─────┬──────────┘  │-http / -sqlite  │
              │                    │              └──────┬──────────┘
    ┌─────────▼──────────┐  ┌─────▼──────────┐         │
    │frameshift-compose   │  │frameshift-     │  ┌──────▼──────────┐
    │(persona composition)│  │catalog (trait) │  │frameshift-memory│
    └─────────┬──────────┘  │frameshift-     │  │(adapter trait)  │
              │              │objects (trait) │  │frameshift-vault │
    ┌─────────▼──────────┐  └─────┬──────────┘  │(vault trait)    │
    │frameshift-source    │        │              └─────────────────┘
    │(TOML schema,        │        │
    │ render, diff, patch)│        │
    └─────────┬──────────┘        │
              │                    │
    ┌─────────▼────────────────────▼──────────┐
    │           frameshift-pack                │
    │  (content addressing, signing, manifest) │
    └──────────────────────────────────────────┘

Crate reference

Foundation

Crate	Role
frameshift-pack	Content addressing (SHA-256), Ed25519 signing, pack manifest schema, capability manifests. Every other crate depends on this.

Persona source and composition

Crate	Role
frameshift-source	Structured TOML persona schema (persona.toml, rules.toml, skills.toml, patterns.toml). Rendering to markdown, semantic diffing, patch operations.
frameshift-compose	Resolves extends (base persona) and mixin overlays. Deterministic layer merge with conflict detection.
frameshift-template	Token placeholders ({{name}}) and section overlays for persona files.

Core engine

Crate	Role
frameshift-client	Install, activate, sync, render, garbage collect. The heart of the CLI. Manages the central store, lockfile, and cache.
frameshift-growth	Append-only JSONL growth log per persona. Local learning that persists across sessions.
frameshift-capabilities	Runtime capability sandbox. Filters tool access and tracks usage against pack manifests.
frameshift-conformance	Test bundle schema, runner trait, scoring, and upgrade regression gate.

Orchestration

Crate	Role
frameshift-orchestrator	Automate mode: context sensing, intent classification, persona ranking, switch controller with hysteresis, preference learning, audit logging.
frameshift-daemon	Background daemon with JSON-RPC 2.0 IPC over Unix socket. File watcher integration. Drives orchestrator evaluation on file changes.

Memory

Crate	Role
frameshift-memory	MemoryAdapter async trait. Store, search, recall, list, forget, health.
frameshift-memory-http	HTTP-backed adapter for external memory services (e.g. Kleos). Bearer token auth, configurable timeout.
frameshift-memory-sqlite-fts	SQLite FTS5 adapter for local full-text search. WAL mode, tag filtering, time-range queries.

Vault and secrets

Crate	Role
frameshift-vault	VaultBackend trait and canonical TOML schema for identity, auth, memory config, preferences, and overlay prose.
frameshift-vault-local	Filesystem backend using age encryption with scrypt passphrase recipients. Atomic writes, zeroized memory.

Runtime

Crate	Role
frameshift-runtime	Loads vault, template, and memory into a single renderable unit. All validation happens in load(); render() is infallible.

Marketplace and distribution

Crate	Role
frameshift-catalog	CatalogBackend async trait (14 methods). Author management, pack publishing, search, version resolution, tombstoning.
frameshift-catalog-postgres	PostgreSQL implementation via diesel-async + bb8 pooling. Embedded migrations.
frameshift-objects	PackStore async trait. Content-addressed put/get/delete/list.
frameshift-objects-fs	Filesystem backend. Sharded directory tree (aa/bb/hash), atomic rename, optional quota.
frameshift-objects-r2	Cloudflare R2 (S3-compatible) backend. No sharding (R2 handles prefix distribution).
frameshift-server	Axum HTTP API. Health, metrics, pack search/list/download, author metadata. Middleware: logging, compression, rate limiting.
frameshift-seed	One-shot seeder binary for bulk-ingesting persona directories into catalog and object store.

Entry points (binaries)

Crate	Role
frameshift-cli	Thin CLI wrapper around the client engine. Clap-derived commands.
frameshift-mcp	Stdio MCP server for Claude integration. Tools and prompts for persona operations.

Design patterns

• Adapter pattern. Pluggable backends via async traits: CatalogBackend, PackStore, MemoryAdapter, VaultBackend. Swap implementations without touching consumers.
• Content addressing. Canonical SHA-256 hashes enable deduplication, integrity verification, and cache sharing across projects.
• Local-first. All persona state lives on your machine. Growth logs never leave your environment. The marketplace is optional.
• Infallible render. Runtime::load() validates everything upfront so Runtime::render() cannot fail.
• Deterministic composition. Base -> mixins -> root, always in declared order, with conflict detection at install time.