How It Works

Contextful is built on Hakiri, an open-source Rust runtime for data pipelines and context layers. This page explains how the pieces fit together.

Architecture overview

graph TB
    subgraph "Your Devices"
        UI[Web / Desktop App]
        MCP_C[MCP Clients]
        LOCAL[Local Context Store]
    end

    subgraph "Contextful Cloud"
        API[API + Auth]
        SYNC[Sync Coordination]
        ORCH[Connector Orchestration]
    end

    subgraph "Hakiri Engine"
        RT[Pipeline Runtime]
        WASM[WASM Connectors]
        IDX[Indexes]
    end

    subgraph "Your Tools"
        QB[QuickBooks]
        GW[Google Workspace]
        SL[Slack]
        MORE[+ more]
    end

    UI --> API
    MCP_C --> API
    API --> SYNC
    API --> ORCH
    ORCH --> RT
    RT --> WASM
    WASM --> QB
    WASM --> GW
    WASM --> SL
    WASM --> MORE
    RT --> LOCAL
    SYNC --> LOCAL
    LOCAL --> IDX

Key principles

Local-first

Your data syncs to your devices as encrypted Parquet files. The cloud layer coordinates sync and runs connectors — it is not the source of truth. If Contextful disappears, your data remains in open formats on your machines.

MCP-native

Every workspace exposes an MCP (Model Context Protocol) server. The web UI, desktop app, Claude Code, Cursor, and any future MCP client all connect through the same interface with the same permissions.

Hakiri under the hood

Contextful doesn’t reinvent data movement. Hakiri handles:

• WASM-sandboxed connectors (typed contracts, hot-swappable)
• DuckDB + Parquet context store (queryable with standard tools)
• Capability-token access control (per-agent scoping)
• Incremental sync with checkpointing

Contextful adds the product layer: OAuth flows, recipe catalog, visual permissions, managed infrastructure.

Data flow

sequenceDiagram
    participant User
    participant Contextful
    participant Hakiri
    participant Source as Data Source

    User->>Contextful: Connect QuickBooks (OAuth)
    Contextful->>Hakiri: Configure pipeline
    Hakiri->>Source: Incremental pull
    Source-->>Hakiri: Records
    Hakiri->>Hakiri: Index (FTS + vector + structured)
    Hakiri-->>Contextful: Sync to user devices
    User->>Contextful: "What invoices are open?"
    Contextful->>Hakiri: context.query
    Hakiri-->>Contextful: Results with provenance
    Contextful-->>User: Answer with citations

Storage format

All data is stored as:

• Parquet files — columnar, compressed, readable by any tool (DuckDB, Pandas, Polars)
• SQLite catalog — metadata, cursor state, schema registry
• Sidecar indexes — HNSW (vector), Tantivy (full-text), zone maps

You can always export and inspect your data with standard tools. No proprietary formats.