Ali Brain - Documentation & Architecture

1. Architecture & Local-First Design

Ali Brain is an entirely browser-based, serverless personal knowledge management system built with React 18 and the File System Access API.

Single JSON Database File: All entries, generated prompt questions, prompt reflection answers, taxonomies, assistant chat histories, and deletion tombstones are stored in a single JSON file on your computer.
IndexedDB Persistence: File handles are retained via idb-keyval so you can resume your active workspace upon reload without picking the file again. An automatic backup snapshot is also written to IndexedDB on every save.
Privacy by Default: Zero telemetry, zero analytics, zero external database servers. Communication occurs solely between your browser and the Google Gemini API when using AI features.

2. Multi-Computer Non-Destructive Sync

When sharing a knowledge base JSON file across multiple devices via cloud sync services (Dropbox, OneDrive, Google Drive, iCloud, or Syncthing), Brain prevents stale overwrites through an entry-level sync engine:

Dirty-State Guard

Computers left open in the background never blind-save stale memory snapshots. If no local changes have been made on that device, auto-save timers will not touch or truncate the file on disk.

Read-Before-Write 3-Way Merge

Before saving local modifications, Brain inspects the file on disk. If another computer wrote to the file, Brain reads and merges entries non-destructively using individual updatedAt timestamps.

Conflict Preservation

If the exact same note was edited concurrently on two computers, the newer timestamp becomes primary, and the older edit is cloned non-destructively as a [Conflict Copy] note so nothing is lost.

Deletion Tombstones

Deleted notes record a timestamped tombstone in the database (tombstones: { [id]: timestamp }). This prevents deleted notes from being resurrected by other computers. Tombstones older than 60 days are pruned automatically.

Live Focus & Background Pulling: Switching to the Brain tab (or while idle) automatically polls the disk file. When remote changes are detected, a pulsing "Synced" badge appears and updates the view seamlessly.

3. Entry Types & Taxonomy Solo Filtering

Every document in Ali Brain is classified into one of five color-coded types:

Notes (Yellow / Amber) • Manual User Thoughts Prompts (Orange) • AI Theme Reflection Notes Media (Red) • Videos & Audio (YouTube/Vimeo) Web (Sky) • Scraped Web Pages & Articles PDFs (Pink) • PDF Documents

Type Filtering Shortcuts:

• Click: Toggles that individual type on or off in the list.

• Shift + Click: Solos that specific type — untoggling all other types in one click. Shift-clicking the active solo type again restores all types back to visible.

• Taxonomies: Filter notes by Projects, Categories, and Tags. Drag notes onto taxonomy tags to assign them. Hover any project, category, or tag in the sidebar to reveal an × button in the left padding to delete it across all notes.

• Pinned Note Card Styling: Note cards in the list sidebar display a left border coded to their entry type. Pinned notes are rendered with a prominent double-thickness (8px) left border compared to unpinned cards (4px), making pinned entries instantly identifiable.

• Column & Card Background Contrast (v2.6.2, v2.7.2): In light mode, the middle note list view features a clean white background contrasting against the off-white backgrounds of the sidebars. Selected note cards adapt seamlessly across themes — setting into a refined shade darker than the background canvas in dark mode (#101010 vs #141414 / #181818) and crisp white in light mode (#ffffff) with a 1px colored line matching their entry type.

• Search Clear / Cancel Action (v2.6.5): When text is entered into the note search bar, an inline cancel icon () dynamically appears on the right edge of the input. Clicking the icon (or pressing Escape) instantly clears search criteria and refocuses the input.

• Taxonomy & Entry-Type Separation (v2.6.8): AI taxonomy generation and auto-tagging strictly forbid categories and tags that overlap with structural entry types or formats (e.g. notes, video/media, web, prompts, pdf), ensuring categories and tags remain focused exclusively on domain topics.

4. Inline Editing & Margin Field Generators

In v2.5.0, the rigid "Edit" button and full-entry edit form were replaced with a fluid, click-to-edit experience:

Double-Click Inline Editing

Double-click any field — Title, Executive Summary, Answer Summary, or individual Takeaway points — to edit it directly in place. Empty fields present subtle placeholders that open a clean editor upon double-clicking. Edits save on blur or Enter.

Margin Auto-Generate Buttons

Round refresh icons hang neatly into the right margin beside generatable fields (Title, Taxonomies, Summary, and Takeaways). Clicking any icon prompts Gemini AI to re-extract or suggest content for only that specific section.

In-Place Taxonomy Editor

Clicking the taxonomy badges in the note header reveals an inline editor right in place. Remove tags with ×, type and press Enter to add new ones, auto-tag via the margin refresh button, or click Done to save.

Distraction-Free Focus Mode

Double-clicking the note body or clicking the Focus Mode button expands the Markdown content into a distraction-free full-screen editor with live auto-saving.

Floating View Toggles & Left Docking on Collapse (v2.6.3): View toggles for the Library () and Notes list () are absolutely positioned in the 50px top padding zone above each respective view. When either view is collapsed, its toggle smoothly glides to the left edge of the screen to allow effortless retoggling at any time. When sidebars are open, smooth 300ms transitions maintain layout stability and scroll state without cluttering the document reader top bar.

Persistent Top-Right Workspace Controls & Seamless Header (v2.6.6): The workspace status pill (showing current file and sync state), settings gear, and workspace options menu are positioned at the top-right corner of the workspace opposite the view toggles. This ensures workspace settings and backup actions are never buried when the taxonomy sidebar is collapsed. The Content View header has also had its solid background color removed for a clean, unified document canvas.

Responsive Prompt Layout (v2.5.3): For Theme Prompt entries, the Prompt Question and Answer Summary cards dynamically adapt to the note's actual available width via CSS container queries. When sidebars expand or the note width collapses below 580px, the cards smoothly transition from side-by-side to a vertical stack for optimal reading comfort.

Saved View Visibility & Layout Persistence (v2.5.4): The active visibility state of all views (Library, Notes list, and AI Assistant) is saved directly into the knowledge base file and restored automatically whenever the file is opened. Selecting or browsing notes now preserves your open views without resetting sidebar states.

5. Content Ingestion & Media Scrubbing

Paste any URL, YouTube link, or raw text into the top ingestion bar:

Web Articles: Uses CORS proxying and turndown to strip navbars, ads, scripts, and footers, extracting clean Markdown into the note content.
Video & Audio: YouTube and Vimeo links embed an interactive player directly inside the note view.
Automatic Metadata Extraction: If Gemini API key is configured, saving a new note automatically generates a concise title, executive summary, 3-5 bulleted key takeaways, and suggested categories/tags.

6. Gemini AI Synthesis & Theme Prompt Generator

Clicking "Generate Prompt" above the note list synthesizes an exploratory reflection question designed to prompt immediate deep thought:

Topic Selection Weighting Hierarchy:

1. Primary Topics (Highest Weight): Manual entries (Yellow Notes). The model grounds questions primarily in your own direct thoughts and reflections.

2. Secondary Topics: Previous prompt responses (Orange Notes). The model explores how your thinking has evolved since earlier reflections.

3. Supporting Context Only: Ingested external entries (Web/Media/PDF). These are never the central subject; they are used only to cross-reference or illuminate manual notes.

Time Span: Evaluates your entire knowledge base across all time, with ~65% weighting given to entries from the last 4 months.

Taxonomy Scope (v2.5.5): When any project, category, or tag filters are active in the sidebar, the prompt generator strictly isolates candidate notes to matching entries (for example, selecting project music feeds only music notes into the prompt generator). Notes written from the resulting prompt automatically inherit the active taxonomy.

Non-Repetition: Remembers all previous prompts in storedPrompts to prevent repeating or closely retreading questions.

7. Unified AI Assistant & Chat Context

The Assistant panel (toggle via Cmd+J / Ctrl+J or the sidebar chat icon) provides an interactive conversational copilot:

Current Entry Mode: Focuses exclusively on the active note to brainstorm, expand, critique, or extract specific concepts.
Whole Brain Mode: Synthesizes across all documents in your library to spot cross-disciplinary patterns and unexpected connections.
Insert Into Note: Click the insert action on any assistant reply to immediately append the text into your active note editor.

8. Backlinks & Decimal Numeric IDs

Ali Brain implements bi-directional knowledge graphs without database dependencies:

Wiki-Style Shortcodes: Typing [[kb-ref:ENTRY_ID]] creates an interactive link to another note. Hovering displays an instantaneous preview modal; clicking selects the target note.
Drag to Reference: Drag any note card from the list into the content editor to auto-insert a formatted backlink.
Chronological Decimal IDs: Every note receives a numeric ID (e.g. #1, #2, #2.1) allowing historical insertions into time gaps while preserving clean numeric chronology.

9. Settings & Version Protocol

Settings are accessible via the gear icon in the workspace header:

Gemini API Keys: Configure one or more Gemini API keys (managed in rotation).
Task-Specific AI Models (v2.6.0): Assign specialized models tailored to each task category:
- Quick Metadata & Summaries: High-speed models for scraping, TL;DR, key takeaways, and auto-tagging.
- Theme Prompts: Balanced models for exploring loose ends and juxtaposing notes.
- AI Assistant Copilot: Interactive chat and whole-brain multi-pass knowledge graph synthesis.
Live API Model Discovery (v2.6.4): Click "Fetch Models from API" to dynamically populate model pickers with 'latest' alias models (e.g. gemini-flash-latest, gemini-pro-latest, gemini-1.5-flash-latest) currently active on your Google AI Studio account, filtering out deprecated snapshots and version clutter, while falling back resiliently to the current medium-speed model (gemini-2.5-flash) when offline.
External Library Merge: Manually merge secondary JSON files into your active workspace with live count reporting.
Version Indicator: Displays current version number (v2.7.2) and provides direct links to the in-app Changelog, Manual, and this documentation file.