Architecture Overview

Cortexa is a Tauri v2 desktop application with a Rust backend and React/TypeScript frontend.

System Diagram

┌──────────────────────────────────────────────────┐
│                  Cortexa Desktop                  │
│  ┌──────────────────────────────────────────────┐│
│  │            React / TypeScript UI              ││
│  │  11 components (modularized from App.tsx)      ││
│  └──────────────┬───────────────────────────────┘│
│                 │ Tauri IPC                        │
│  ┌──────────────▼───────────────────────────────┐│
│  │              Rust Backend                      ││
│  │                                                ││
│  │  ┌─────────┐ ┌──────────┐ ┌───────────────┐  ││
│  │  │ Storage  │ │ Agent    │ │ LLM Providers │  ││
│  │  │ SQLite   │ │ Pipeline │ │ Ollama/Cloud  │  ││
│  │  │ + Blobs  │ │ + Queue  │ │               │  ││
│  │  └─────────┘ └──────────┘ └───────────────┘  ││
│  │                                                ││
│  │  ┌─────────┐ ┌──────────┐ ┌───────────────┐  ││
│  │  │ HNSW    │ │ HTTP API │ │ Hive Client   │  ││
│  │  │ Index   │ │ + MCP    │ │ (WebSocket)   │  ││
│  │  └─────────┘ └──────────┘ └───────────────┘  ││
│  └──────────────────────────────────────────────┘│
└──────────────────────────────────────────────────┘
         │              │              │
    ┌────▼────┐   ┌─────▼─────┐  ┌────▼─────┐
    │  CLI    │   │ MCP Bridge│  │ Hive     │
    │         │   │ (stdio)   │  │ Server   │
    └─────────┘   └───────────┘  └──────────┘

Crate Structure

Crate	Purpose
cortexa (src-tauri)	Desktop app: Tauri commands, storage, agents, API, sync
cortexa-cli (cli)	Standalone CLI binary
cortexa-mcp (mcp)	Standalone MCP stdio bridge
cortexa-hive (hive)	P2P relay server
hive-protocol	Shared wire-format types

Data Flow

Capture

Input → parse_template → encrypt(AES-256-GCM) → write blob
                       → ingest_text(SQLite) → enqueue(Embed)
                       → enqueue(Summarize) if enabled
                       → auto_share_to_hive if enabled

Search

Query → FTS5 keyword search (BM25 scoring)
      → HNSW semantic search (cosine similarity)
      → merge_search_results (weighted blend)
      → apply_context_boosts (project, file-path)
      → return ranked ScoredItems

Deep Think

Item → Expand (thinking lenses, sub-questions)
     → Counterpoint (critique, contradiction detection vs. archive)
     → Synthesize (structured JSON brief with readiness gates)

Background Reflection

tick_schedules() (every 60s, configurable interval)
     → Load recent N items since last reflection
     → LLM analysis: themes, contradictions, patterns, gaps, connections
     → Store as type:reflection item
     → Run confidence decay on all items
     → Tag stale items (below threshold)

Cross-User Synthesis

Hive import (item with thesis) → semantic search local vault
     → Find local items with theses on similar topics
     → LLM synthesis: agreements, disagreements, novel combinations
     → Store as type:cross-synthesis item with links to both sources

Confidence Decay

Ingest → assign initial score (0.5–0.8 based on source)
Reflection pass → decay: score * (rate ^ weeks_since_validated)
User interaction (pin/edit) → reset last_validated_at
Contradiction detected → penalty applied to both items
Below threshold → tagged confidence:stale

Key Design Decisions

• Local-first: All data stays on-device unless you explicitly enable sync or Hive
• Encryption by default: Content blobs are AES-256-GCM encrypted. Embeddings are stored as raw floats (derived data, not sensitive)
• HNSW for scale: In-memory approximate nearest neighbor index builds on startup, updates incrementally, auto-rebuilds when the pending buffer grows
• FTS5 for precision: Full body content indexed for exact keyword matching
• Hybrid merge: Configurable blend of semantic and keyword scores
• WAL mode: SQLite write-ahead logging for better concurrent read performance during background jobs
• Job queue: 2 background workers with priority scheduling (embed=0 through reflection=6) process embed, summarize, expand, counterpoint, synthesize, research, briefing, reflection, and cross-synthesis jobs with retry and dead-letter handling
• Collective cognition: Reflection outputs and cross-synthesis results are stored as regular items (not separate entities) — they participate in search, Hive sharing, and knowledge graph linking like any other thought