Cortexa

Appearance

How-Tos ​

Short, task-oriented recipes for getting things done in Cortexa. Each one is self-contained — skim the headings and jump to what you need. For conceptual background, follow the links into the rest of the guide.

Capture ​

Capture a thought with the global hotkey ​

  1. Press the capture hotkey from anywhere (set in Settings → Capture).
  2. A popup opens already focused on the editor — type and press Save.
  3. Choose where it appears in Settings → Capture → Capture mode: over the taskbar, centered on screen, or a full window.

The item is encrypted, embedded for semantic search, and (if enabled) auto-summarized in the background.

Capture from the command line ​

bash
cortexa-cli capture "Switched the cache to an LRU — TTL was evicting hot keys"
cortexa-cli capture --project Cortexa --tags perf,cache "..."

Add --json to any CLI command for machine-readable output.

Capture from an AI agent (MCP) ​

From Claude Code, Cursor, Codex, or any MCP host:

cortexa_capture(
  content="Fixed the Range handler panic on 0-byte files",
  thought_type="debug",
  project="Cortexa",
  agent="claude-code",
  tags=["hive","bugfix"]
)

Use cortexa_ingest for plain text, or cortexa_capture when you want structured metadata. See MCP Tools.

Auto-extract tags from content ​

Type #hashtags directly in the capture body. They're parsed server-side, so the same behavior applies whether the capture came from the app, MCP, the API, the CLI, or the extension. You can also add tags explicitly.

Use a template / slash trigger ​

Define slash triggers in Settings → Templates (e.g. /idea:, /todo:). Then capture /todo: ship the docs update and the configured tags + actions apply automatically. Triggers are parsed canonically server-side, so every ingestion path benefits.

Search & Navigate ​

Press / (or click the search box) and type. Cortexa blends semantic (HNSW vector) and keyword (FTS5) signals. Exact-looking queries — function names, identifiers — automatically boost the keyword weight. Use a trailing * for prefix search (error*).

Tune the keyword/semantic balance ​

Settings → Search exposes the blend weight (default 0.3 keyword / 0.7 semantic) and an optional LLM re-ranker that reorders the top-K results. Lower the semantic weight for code-heavy vaults; raise it for conceptual notes.

Filter and sort the list ​

  • Sort by newest / oldest / recently updated / A–Z — the choice persists across sessions.
  • Date range — set from/to pickers in the filter bar, or use the quick presets (Today, 7d, 30d).
  • Project — pick the active project in the switcher; the filter persists across restarts.
  • Tags — click any tag chip to filter by it.

Keyboard shortcuts ​

KeyAction
/Focus search
nNew capture
j / kMove between cards
EscClose the open card / drawer

A floating back-to-top button appears once you scroll.

Think & Analyze ​

Run Deep Think on a thought ​

Open any saved thought and click Deep Think. Cortexa runs Expand → Critique → Synthesize (or the full orchestrator, depending on settings) and produces a structured thesis: { core, supporting_arguments, risks, next_steps }. Jobs auto-recover on restart if interrupted.

Preview the plan before running ​

Click Preview Plan to see the orchestrator's execution plan step-by-step, then approve it before any LLM calls are made. Useful when you want to control cost or see which agent tools will fire.

Trigger a reflection pass ​

Reflection runs on a schedule, but you can force one from Settings → Cognition or via cortexa_reflection. It analyzes recent thoughts for themes, contradictions, patterns, and gaps, storing the result as a type:reflection item. It's novelty-gated, so repeat passes won't pollute the vault.

Generate speculative insights (Dream agent) ​

Enable Settings → Cognition → Dream agent, or click Dream now on the Dreams page, to recombine distant thoughts into low-confidence speculative insights you can accept or dismiss. See Dream Agent.

Check why an item's confidence changed ​

Every confidence change is logged with a reason. Call cortexa_confidence_history(item_id) (or view the badge on the card) to see the full audit trail — decay, contradiction penalties, thesis boosts, and interaction resets.

Audio Briefings ​

Brief a single thought ​

Click the Brief button on any thought. Cortexa generates a spoken briefing (OpenAI TTS or local Piper), stores the mp3 encrypted, and lets you play it inline.

Generate a daily briefing from recent items ​

In Settings → Briefings, set the number of recent items and enable the scheduled daily briefing. Use Run scheduled tasks now to test it immediately. Audio syncs to Hive peers and appears on published blog pages with a collapsible transcript.

Use fully-local TTS (no cloud) ​

Select Piper as the TTS provider in Settings → Briefings. Piper is bundled and runs entirely on-device — no API key, no network.

Connect Agents ​

The app already serves MCP at POST http://127.0.0.1:7373/mcp. Point any HTTP-capable MCP host straight at it using the bearer token from Control panel → External. No extra binary needed. See MCP Setup.

Use the stdio bridge (Claude Desktop, Codex) ​

For hosts that only speak stdio:

bash
cargo build -p cortexa-mcp --release   # → target/release/cortexa-mcp
cortexa-cli config --url http://127.0.0.1:7373 --token <TOKEN>

The bridge reads the CLI config automatically; CORTEXA_URL / CORTEXA_TOKEN env vars override it. See the per-host snippets in the README.

Give an agent zero-prompt context ​

Run cortexa_sync_context (or the CLI equivalent) inside a project directory to generate .cortexa-context.md. Any agent that reads project files — Claude Code, Cursor — then starts with your decisions, patterns, and TODOs without calling a single tool. See Context Injection.

Coordinate two agents live (NRTMF) ​

Have each agent read the channel before working and broadcast cross-cutting changes:

cortexa_feed(channel="cortexa-audit", since=cursor, exclude_agent="audit-backend")
cortexa_capture(channel="cortexa-audit", agent="audit-backend", thought_type="architecture", content="...")

Watch it live in the Feed tab. Full walkthrough in Live Agent Feed (NRTMF).

Issue a revocable token per integration ​

In Control panel → External → Tokens, issue a separate bearer token for each client (extension, scheduled job, second laptop). Revoke any one without affecting the others, instead of sharing the keychain-issued global token.

Hive (P2P Sharing) ​

Connect to a Hive relay ​

In Control panel → Hive connections, add a connection with the relay URL. Set the direction (Send & Receive / Receive Only / Send Only), and toggle auto-share, auto-import (with per-project routing), and auto-publish per connection. Use Test connection to verify before saving.

Share a thought to peers ​

With a connection in a sending direction, enable auto-share, or share an item manually. Full structured data (thesis, summary, notes, conversation) transfers to peers. Offline shares queue with a hive:pending-share tag and flush on reconnect.

Publish a thought as a blog post ​

Enable auto-publish on a connection (with its admin token), or publish an item manually. Cortexa renders a static HTML blog with search, tag filters, a date-range picker, reading-time estimates, and Open Graph cards. List published URLs with cortexa_publications.

Run your own Hive server ​

Build and deploy the standalone relay (see Hive Server deployment). It bridges multiple Cortexa instances over WebSocket and handles binary file transfer and blog publishing.

Sync & Backup ​

Sync across devices ​

Settings → Sync writes encrypted-only blobs to a filesystem folder or any S3-compatible backend (R2, B2, MinIO, AWS). On a second device, use the guided join existing vault flow — it validates your passphrase against the remote manifest before writing anything locally. See Sync Backends.

Back up and restore the vault ​

Settings → Backup produces a single-file .tar.gz snapshot of the encrypted blobs + DB + salt. Restore from the same panel. A Markdown export is available too, with an explicit "this leaves the vault unencrypted" warning.

Set retention rules ​

Settings → Retention auto-archives after N days and moves deletions to trash with a grace period before hard-delete. Run a manual VACUUM to reclaim space.

Security ​

Lock the vault when idle ​

Enable idle auto-lock in Settings → Security to clear the working key after N minutes of inactivity. A full-viewport lock screen then gates the UI, the HTTP API, MCP, background workers, and the Telegram poller until you re-enter the passphrase. Off by default.

Understand what's encrypted ​

Every item is AES-256-GCM encrypted with an Argon2-derived key before it touches disk; the passphrase lives in the OS keychain. Search works without bulk-decrypting: FTS5 indexes summary/body/preview and HNSW indexes the embedding vector. See Encryption.

Customize the Experience ​

Change theme and density ​

Settings → Appearance offers 18 themes (System, Light, Dark, Midnight, Sunset, Forest, Lavender, Rose, Ocean, Copper, Slate, Neon, Cherry, Aurora, Sand, Storm, Ember, Arctic) with color-preview swatches, compact/comfortable density, and a font-scale slider (0.7×–1.6×). All motion respects prefers-reduced-motion.

Organize with projects and principles ​

Create a project (auto-created on first capture, or via the switcher) to scope search, filtering, and context injection. Mark any thought as a Principle to surface it in all project-scoped searches — ideal for engineering standards and technology preferences that apply everywhere.

Set per-source capture defaults ​

In Settings → Templates / Sources, give captures from Telegram, MCP, the extension, and the in-app popup different default actions. Each path identifies itself via X-Cortexa-Source, so the right defaults apply automatically.

Troubleshooting ​

SymptomTry this
Agent isn't getting contextConfirm the MCP host points at http://127.0.0.1:7373/mcp with the right token; re-run cortexa_sync_context for file-based injection
Search misses an obvious matchCheck the keyword/semantic blend; for identifiers, add a trailing * or raise keyword weight
Build-thesis button stuckA stale in-progress thesis can disable it — reload the item; this was hardened in v0.14
Feed tab shows nothingMake sure both agents use the same channel string and that a Hive connection is up between the machines
Vault won't unlock after syncUse the join existing vault flow, which validates the passphrase against the remote manifest first

For deeper architecture questions, see the Architecture overview.

Built with Rust, Tauri, and a lot of captured thoughts.