Voxa/Architecture Specification

Zero-Knowledge Memory & MCP Gateway

Complete technical architecture of Voxa: a developer-first memory palace designed for human reflection, voice capture, and AI agent context via the Model Context Protocol.

● Production SpecMCP Protocol 2025/2026Zero-Knowledge Pass-Through

1. Executive Summary & Core Philosophy

Unlike traditional platforms where private notes and reflections are held on centralized company servers, Voxa operates strictly as a Zero-Knowledge Pass-Through Broker:

  • Zero Content Custody: Voxa servers never store, read, or hold user journal entries, voice memos, reflections, or AI conversations.
  • Total Elimination of Local Vault: All reads and writes are direct, stateless transactions to the user's chosen cloud vault. No local SQLite or JSON vault files are retained on server disks.
  • User-Owned Storage: All memories live exclusively in the user's personal Notion Database or GitHub Gist.
  • Ambient MCP Integration: AI agents (Claude Desktop, Cursor, Antigravity, VS Code) query past reflections and ambiently log breakthrough moments without context switching.

2. Model Context Protocol (MCP) Implementation

Voxa implements a high-performance dual-transport MCP server supporting both Server-Sent Events (SSE) for continuous streaming and JSON-RPC 2.0 message dispatching.

Stream Endpoint

GET /api/mcp/sse

Establishes persistent SSE stream with keepalive pings and returns immediate sessionId registration.

Message Endpoint

POST /api/mcp/message

Handles authenticated JSON-RPC tool calls and resource reads using Bearer vx_live_... tokens.

Registered MCP Tools

Tool NameParametersAction
voxa_create_entrycontent, title, type, tags, moodPersists a new reflection directly into Notion or GitHub Gist.
voxa_search_entriesquery, tag, limitFull-text and hashtag semantic search across past memories.
voxa_get_daydate (YYYY-MM-DD)Fetches today's or any past day's briefing in formatted Markdown.
voxa_get_streaknoneCalculates reflection streak, active days, and frequent hashtags.

3. Notion as a Database

When Notion is selected, Voxa automatically provisions any standard page into a multi-dimensional relational database using both standard endpoints and Notion API v5 Data Sources.

Auto-Provisioned Schema

  • Name (title): Headline or short summary.
  • Tags (multi_select): Categorization tags (#mcp, #learning, #idea, etc.) with hashtag fallback parsing.
  • Type (select): moment, idea, task, event, or mood.
  • Mood (select): great, good, okay, low, or stressed.
  • Date (date): Timestamp and calendar grouping.
  • Content (rich_text): High-speed inline preview for table views.
  • VoxaId (rich_text): Unique cross-platform UUID for idempotent updates.

Dual-Write Pattern

Key properties are written to page columns for table filtering, sorting, and gallery views, while unrestricted full-length Markdown is chunked into 2,000-character blocks and stored directly as page body paragraphs (children).

4. GitHub Gist as a Database

For developers who prefer git-native storage, Voxa creates an encrypted private Gist containing a single structured voxa-journal.json document.

  • Immutable Git History: Every journal update creates an atomic commit in your personal Gist. You can inspect diffs and rollback history anytime.
  • Zero Lock-In: Standard JSON format that can be cloned locally or backed up offline.
  • Atomic Writes: Uses GitHub's atomic patch API to prevent concurrent write collisions.

5. Multi-Factor Deduplication Engine

To prevent duplicate cards when multiple clients (voice input, Claude Desktop, Cursor) log reflections simultaneously, entries are verified across three tiers:

  1. Primary UUID: Matches unique entry.id.
  2. Notion Page ID: Matches exact Notion page UUID.
  3. Normalized Content Signature: Checks (title + content + dateKey).toLowerCase() against active memory cache to prevent duplicate cards during real-time sync.

6. MCP Host Configuration

Connect Claude Desktop or Cursor to your Voxa instance:

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "voxa": {
      "url": "http://localhost:4321/api/mcp/sse",
      "headers": {
        "Authorization": "Bearer vx_live_YOUR_TOKEN_HERE"
      }
    }
  }
}

Cursor (.cursor/mcp.json)

{
  "mcpServers": {
    "voxa": {
      "url": "http://localhost:4321/api/mcp/sse",
      "headers": {
        "Authorization": "Bearer vx_live_YOUR_TOKEN_HERE"
      }
    }
  }
}