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.
GET /api/mcp/sse
Establishes persistent SSE stream with keepalive pings and returns immediate sessionId registration.
POST /api/mcp/message
Handles authenticated JSON-RPC tool calls and resource reads using Bearer vx_live_... tokens.
Registered MCP Tools
| Tool Name | Parameters | Action |
|---|---|---|
| voxa_create_entry | content, title, type, tags, mood | Persists a new reflection directly into Notion or GitHub Gist. |
| voxa_search_entries | query, tag, limit | Full-text and hashtag semantic search across past memories. |
| voxa_get_day | date (YYYY-MM-DD) | Fetches today's or any past day's briefing in formatted Markdown. |
| voxa_get_streak | none | Calculates 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:
- Primary UUID: Matches unique
entry.id. - Notion Page ID: Matches exact Notion page UUID.
- 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"
}
}
}
}