Cognir Platform Overview

Cognir is a local-first, AI-augmented knowledge work environment designed for deep engagement with complex textual material. It provides an integrated pipeline for document ingestion, semantic concept extraction, active annotation, multi-page note composition, three-dimensional knowledge graph construction, and structured output compilation.

The platform operates entirely within the browser. No data is transmitted to external servers except direct API calls to the configured AI provider. All persistent state — documents, annotations, notes, and knowledge graphs — is stored in IndexedDB with a localStorage fallback.

Core Capabilities

Quickstart

This section provides a minimal path to first value. Users can be operational within two minutes of initial load.

Step 1: Configure an API Key

Cognir requires an API key from a supported AI provider to perform semantic extraction and knowledge graph synthesis. The platform ships with a shared default Groq key for immediate evaluation, but users are strongly encouraged to provision their own key for production use.

1. Click the Settings button (☰) in the top-right corner of the landing page.
2. Paste your API key into the input field. The system will auto-detect the provider based on key prefix.
3. Click Save Key. The key is stored exclusively in your browser's IndexedDB.

Step 2: Import a Document or Start a Note

From the landing page, users have two entry points:

• Load Document — Upload a PDF, DOCX, TXT, or Markdown file. The system will extract text, perform AI-driven concept extraction, and present an annotated reader view.
• Try Cognir — Opens the multi-page note editor directly with a pre-built starter document demonstrating the annotation and graph workflow.

Step 3: Annotate and Build

Once in the reader or note editor, select any text to trigger the annotation popup. Write your reaction or analysis. After accumulating annotations, click Graph to generate the 3D knowledge map. Finally, click Compile Output to export your synthesized knowledge.

Architecture

Cognir is a single-page application delivered as a self-contained HTML file. It requires no build step, no server, and no installation. The architecture is intentionally minimal to reduce attack surface and maximize portability.

Runtime Dependencies

Data Flow

─────────────┐ ┌──────────────┐ ┌─────────────┐ ┌──────────────┐
│ File Input │────▶│ Text Extract│────▶│ AI Extract │────▶│ Concept │
│ (PDF/DOCX/ │ │ (pdf.js / │ │ (Provider │ │ Model │
│ TXT / MD) │ │ mammoth) │ │ API call) │ │ (JSON) │
└─────────────┘ ──────────────┘ └─────────────┘ └──────────────┘
│
▼
┌─────────────┐ ┌──────────────┐ ┌─────────────┐ ┌──────────────┐
│ Export │────│ Zettelkasten│◀────│ Annotation │◀────│ Reader / │
│ (TXT) │ │ Graph (3D) │ │ System │ │ Note Editor │
└─────────────┘ └──────────────┘ └─────────────┘ └──────────────┘

Storage Architecture

All persistent data is stored in a single IndexedDB database (cognir_db) with one object store (state). The entire application state is serialized as a single JSON document keyed under cognir_v3. A localStorage fallback (cognir_v2) is maintained for compatibility.

IndexedDB: cognir_db
── Object Store: state
│ └── Key: cognir_v3
│ └── Value: {
│ theme: "dark" | "light",
│ apiKey: string,
│ spellCheck: boolean,
│ pages: Page[],
│ currentPageId: string,
│ doc: Document | null,
│ hl: Record<string, Annotation[]>,
│ ac: number,
│ version: "cognir_v3"
│ }

Core Concepts

Annotation

An annotation is a structured pairing of a selected text span (the highlight) and a user-authored thought (the note). Annotations are the atomic unit of engagement in Cognir. Each annotation carries a unique identifier, a reference to its source context, and a boolean flag controlling its inclusion in the Zettelkasten graph.

Concept

A concept is an AI-extracted thematic unit from a source document. Each concept contains a title, summary, consolidated content passage, and a list of key theses (arguments). Concepts form the navigable structure of the document reader.

Zettelkasten Node

A Zettelkasten node is an atomic idea extracted from the union of source material and user annotations. Nodes are typed (insight, concept, question, connection, tension), contain a short title (≤7 words), a 1–2 sentence synthesis, optional source highlights, and explicit connections to other nodes. The resulting graph is the platform's primary knowledge artifact.

Page

A page is an independent note document within the multi-page editor. Each page has its own title, HTML content, annotation set, and optional cached knowledge graph. Pages can be individually selected for graph synthesis via the Page Specific feature.

Graph Fingerprint

A content-derived signature computed from a page's annotations and content length. The fingerprint enables cache-based instant graph rendering: if the fingerprint matches a previously computed graph, the system skips the AI call and renders immediately.

Importing Documents

Cognir supports four document formats for ingestion. The import interface accepts single or multiple files via drag-and-drop or file browser selection.

Supported Formats

Multi-File Processing

When multiple files are uploaded, Cognir processes each sequentially with progress indication, then concatenates the extracted texts with file-name delimiters (=== filename ===) before performing unified concept extraction. This enables cross-document analysis.

Text Extraction Pipeline

The extraction pipeline is format-specific and operates entirely in the browser's main thread. For PDFs, the system performs coordinate-aware text reconstruction to preserve reading order.

PDF Extraction Algorithm

1. The PDF binary is loaded into an ArrayBuffer and parsed by PDF.js.
2. For each page, the text content layer is retrieved with whitespace normalization enabled.
3. Text items are grouped by their vertical position (Y-coordinate, rounded to 0.1pt precision).
4. Rows are sorted top-to-bottom; items within each row are sorted left-to-right by X-coordinate.
5. Items are concatenated with single-space delimiters to reconstruct lines.
6. Pages are separated by double newlines.

// Coordinate-aware reconstruction
const rows = {};
tc.items.forEach(it => {
const y = Math.round(it.transform[5] * 10) / 10;
if (!rows[y]) rows[y] = [];
rows[y].push({ x: it.transform[4], str: it.str });
});
// Sort: top-to-bottom, then left-to-right
Object.keys(rows).map(Number).sort((a,b) => b-a).forEach(y => {
const line = rows[y].sort((a,b) => a.x-b.x)
.map(it => it.str).join(' ').trim();
if (line) out += line + '\n';
});

AI Concept Extraction

After text extraction, the system performs AI-driven semantic analysis to identify conceptual themes, arguments, and structural elements. The extraction strategy adapts to document length.

Single-Chunk Extraction

Documents under 8,000 characters are processed in a single AI call. The system prompt instructs the model to extract all conceptual themes while preserving original wording, returning a structured JSON object containing title, overview, and an array of concepts with titles, summaries, content, and theses.

Multi-Chunk Extraction

Documents exceeding 8,000 characters are split into chunks of 8,000 characters with a 500-character overlap window. A maximum of 6 chunks are processed. Each chunk is analyzed independently, then the resulting concept lists are merged via a secondary AI call that deduplicates, consolidates, and synthesizes across sections.

Retry and Backoff Strategy

The AI call layer implements exponential backoff with jitter for rate-limit and network errors:

• Rate limit errors: Base delay 8,000ms, multiplied by 2.2^attempt, capped at 38,000ms
• Network errors: Base delay 4,000ms, same multiplier and cap
• Maximum retries: 3 attempts per call
• Progress feedback: Users see countdown timers and attempt numbers during backoff periods

Reader & Annotation Interface

The reader presents extracted concepts in a three-column layout: concept navigation sidebar, main content area, and annotation panel.

Layout Structure

Annotation Interaction

Text selection anywhere in the main content area (title, overview, summary, theses, or body) triggers an annotation popup positioned above the selection. The popup displays the selected text as a truncated quote and provides a text input for the user's thought.

• Enter — Saves the annotation
• Escape — Cancels without saving
• Cancel button — Dismisses the popup

Saved annotations are highlighted in the source text with a subtle background and border. Hovering a highlight cross-highlights the corresponding annotation card, and vice versa. Clicking a highlight scrolls the annotation panel to the matching card.

Annotation Deletion

Each annotation card includes a delete button (×). Deletion is immediate and irreversible within the session; the annotation is removed from the highlight map and the view re-renders.

Multi-Page Note Editor

The note editor is a rich text composition environment supporting multiple independent pages, each with its own annotation set and optional cached knowledge graph. It is the primary workspace for original thought composition.

Editor Architecture

The editor uses a contenteditable div with the Lora serif typeface for prose composition. Content is stored as HTML, enabling rich formatting persistence. All edits are auto-saved to IndexedDB on every input event.

Multi-Page System

Each note document can contain multiple pages, accessible via a collapsible left sidebar. Pages are independent units with separate titles, content, annotations, and graph caches.

Page Operations

Page Data Model

{
id: string, // 'p' + timestamp(36) + random(36)
title: string, // User-editable; defaults to 'Untitled Note'
html: string, // Editor innerHTML
annotations: Annotation[],
created: number, // Date.now() at creation
updated: number, // Date.now() at last edit
graph: ZettelGraph | null, // Cached knowledge graph
graphFp: string | null // Content fingerprint for cache validation
}

Rich Formatting Toolbar

The formatting toolbar provides grouped controls for text styling, structural elements, list management, and special insertions.

Style Group

Heading Group

List Group

Insert Group

Math Symbol Palette

The math palette provides 47 symbols organized in an 8-column grid, including summation (∑), integral (∫), partial derivative (∂), infinity (∞), Greek letters (α, β, γ, δ, θ, λ, μ, σ, ω, φ, ψ), set theory operators (∈, ∉, ∩, ∪, ⊂, ⊃), logic symbols (∀, ∃, ¬, ∧, ∨), number sets (ℝ, ℤ, ℕ, ℚ, ℂ), and miscellaneous operators. Symbols are inserted at the current cursor position.

Paste Behavior

All pasted content is stripped of formatting. Images are the sole exception — image data from the clipboard passes through natively. Text is inserted as plain text via execCommand('insertText'), ensuring no external fonts, colors, or styles contaminate the document.

Image Width Cycling

Clicking an image in the editor cycles its width through three states: 100% → 60% → 30% → 100%. A brief selection border confirms the change.

Annotation Mode Toggle

The editor features a toggle switch in the toolbar that controls whether text selection triggers the annotation popup.

The toggle state is session-scoped and resets to Annotate on each editor load. A toast notification confirms each state change.

Reading Mode (Zen Mode)

Reading Mode provides a distraction-free writing environment by hiding all auxiliary UI elements.

What Reading Mode Hides

• Formatting toolbar
• Pages sidebar
• Annotation panel (right column)
• Top bar mid-section label

What Reading Mode Shows

• Top navigation bar (with Reading toggle button)
• Editor content area (centered, max 720px, with 80px vertical padding)
• Bottom info bar (reduced opacity, reveals on hover)

Reading Mode is toggled via the Reading button in the top navigation bar. The button shows an active state when the mode is engaged.

Zettelkasten Knowledge Graph

The Zettelkasten system transforms annotations and source material into a structured graph of atomic ideas. The graph is the platform's primary knowledge artifact — a navigable, three-dimensional map of connected thinking.

Graph Construction Pipeline

1. Input aggregation: The system collects all annotations marked for Zettelkasten inclusion, plus the full note body or document context (up to 5,500 characters).
2. AI synthesis: A structured prompt instructs the AI to extract 14–30 nodes (depending on input richness), each typed and connected to 2–5 other nodes.
3. Cache validation: For note-based graphs, a content fingerprint is computed. If the fingerprint matches a cached graph, the AI call is skipped and the cached graph renders instantly.
4. 3D layout: Nodes are positioned via a force-directed algorithm (140 iterations of repulsion + attraction), then rendered in WebGL.

Node Count Heuristics

Type Distribution Targets

3D Graph Visualization

The knowledge graph is rendered as an interactive three-dimensional scene using Three.js. Nodes are represented as colored spheres with glow effects; edges are rendered as lines with particle streams indicating connection flow.

Rendering Specifications

Force-Directed Layout

Nodes are initialized on a Fibonacci sphere distribution, then refined through 140 iterations of force simulation:

• Repulsion: All node pairs repel with force proportional to 1/d², scaled by cooling factor
• Attraction: Connected nodes attract with spring force (rest length 3.8 units)
• Damping: Velocity multiplied by 0.52 each iteration
• Cooling: Force magnitude scales by (1 - iteration/140)

Node Type Color System

Each node type is assigned a distinct color that is consistent across nodes, edges, glow effects, labels, and filter buttons.

Node size is proportional to degree (total connections, both outgoing and incoming). Higher-degree nodes appear larger and more prominent in the visualization.

Filters & Navigation

Type Filters

A filter bar at the top of the graph view allows users to isolate nodes by type. The All filter is active by default. Selecting a specific type dims all non-matching nodes and their edges.

Camera Controls

Node Selection Behavior

When a node is selected:

• The selected node scales to 2.5× and turns white (dark mode) or black (light mode)
• Directly connected nodes scale to 0.92× and retain their type color
• All other nodes scale to 0.7× and dim to a neutral gray
• Edges between the selected node and its connections become fully opaque
• All other edges dim to 8% opacity
• The detail panel slides in from the right showing title, type, content, source highlights, and connections

Editing Nodes

The detail panel includes an inline editor for modifying node properties without regenerating the entire graph.

Editable Fields

Connection Management

• Add connection: Select a target node from the dropdown and click Add. The connection is added bidirectionally in the data model, and the 3D graph re-renders to show the new edge.
• Remove connection: Click the × button next to any connection in the list. The edge is removed and the graph re-renders.

Changes are saved to the in-memory graph object and persisted to IndexedDB. The 3D visualization updates immediately after each save.

Compilation & Export

The export module transforms the Zettelkasten graph into structured prose via AI synthesis. Users select a format, and the system generates a compiled document that can be edited, copied, or downloaded.

Export Pipeline

1. User selects an export format from the four available options.
2. The full Zettelkasten JSON (nodes, synthesis, open questions) is sent to the AI with a format-specific style prompt.
3. The AI returns compiled text, which is displayed in an editable textarea.
4. User can edit the output directly, then copy to clipboard or download as a .txt file.

Export Formats

API Key Management

Cognir requires an API key from a supported AI provider for all AI-driven operations: concept extraction, knowledge graph synthesis, and export compilation. Keys are stored exclusively in the browser and are never transmitted to any party except the configured AI provider.

Key Detection

The system auto-detects the provider based on key prefix:

Keys that do not match any known prefix are flagged as Unrecognised and cannot be saved.

Key Storage

API keys are stored in IndexedDB as part of the application state JSON. The key is accessible only within the browser session and is sent directly to the provider's API endpoint via fetch requests. No intermediary server processes or logs the key.

AI Provider Configuration

Provider Endpoints

Provider Recommendations

Data Storage Architecture

Primary Storage: IndexedDB

All application state is persisted in an IndexedDB database named cognir_db (version 1). The database contains a single object store (state) with one record keyed as cognir_v3. This record holds the complete serialized application state as a JSON string.

Fallback Storage: localStorage

A secondary copy of the state is maintained in localStorage under the key cognir_v2. This serves as a compatibility fallback in environments where IndexedDB is unavailable or restricted.

Save Triggers

The system writes to storage on every meaningful state change:

• Editor content changes (on every input event)
• Annotation creation or deletion
• Page creation, deletion, or title change
• API key save
• Theme change
• Spell check toggle
• Graph cache update

Load Sequence

1. Attempt to read from IndexedDB.
2. If IndexedDB fails or returns null, fall back to localStorage.
3. If both fail, initialize with default state (empty pages, default API key).
4. On first visit (no pages and no document), inject the starter document.

Themes & Preferences

Theme System

Cognir supports two themes controlled by CSS custom properties on the <body> element:

Theme preference is persisted in storage and applied on application load. The 3D graph renderer also adapts its color palette, starfield, and background color to the active theme.

Spell Check

Spell check is controlled via a toggle in Settings. When enabled, the spellcheck attribute is set to true on the editor element. The preference persists across sessions.

Backup & Import

Export All Data

The Settings panel provides an Export All Data (JSON) button that serializes the complete application state (theme, API key, spell check preference, all pages, current document, highlights, and version identifier) into a JSON file with a timestamped filename (cognir_backup_YYYY-MM-DD.json).

Import Data

The Import Data (JSON) button opens a file picker accepting .json files. The system validates that the file contains a version field starting with cognir. Upon confirmation, the imported data replaces all current state. The application re-renders immediately after import.

Keyboard Shortcuts

Editor Shortcuts

Annotation Popup Shortcuts

General Navigation

Troubleshooting

Rate Limit Errors

Symptom: Error message mentioning rate limits, 429 status, or quota exhaustion.

Cause: The shared default Groq key has limited capacity. During periods of high concurrent usage, the key may hit rate limits.

Resolution: Provision your own free Groq API key at console.groq.com. This provides dedicated capacity and eliminates shared-key contention.

Network Errors

Symptom: "Failed to fetch" or network timeout errors.

Cause: Intermittent connectivity issues or provider-side outages.

Resolution: Verify internet connectivity. The system implements automatic exponential backoff with up to 3 retries. If the issue persists, try switching providers.

Malformed JSON Response

Symptom: "AI returned malformed JSON" error.

Cause: The AI provider returned a response that could not be parsed as valid JSON, possibly due to model hallucination or output truncation.

Resolution: Retry the operation. The system includes robust JSON parsing with markdown fence stripping and object extraction. If the error persists consistently, consider switching to a higher-quality provider (Anthropic or OpenAI).

Empty PDF Extraction

Symptom: "No text extracted from PDF" error.

Cause: The PDF is image-based (scanned document) or encrypted.

Resolution: Convert the PDF to a text-based format using OCR software before importing, or use the note editor to manually transcribe key passages.

Graph Not Updating

Symptom: Clicking "Graph" shows the cached version despite new content.

Cause: The content fingerprint has not changed (no new annotations or content length change).

Resolution: Add new annotations or modify the note content. The fingerprint is computed from annotation IDs, notes, and content length. Any meaningful change will trigger a fresh AI synthesis.

Glossary