Ali Brain - Documentation & Architecture

1. Architecture & Local-First Design

Ali Brain is an autonomous, serverless personal knowledge management system that runs entirely in your browser using standard web technologies. It stores your complete database directly on your local file system, providing instant load times, complete data ownership, and offline capability without relying on centralized databases or servers.

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.
Dedicated Folder Recommended: It is strongly recommended to create and store your library inside its own dedicated folder (e.g. ~/Documents/Brain/BrainLibrary.json) rather than directly in a root or general documents directory.
Temporary Swap Files (.crswap): In Chromium browsers (Chrome, Edge, Brave), data is written atomically by creating a temporary swap file (*.crswap) in the same directory before renaming it to your JSON file. If your folder is synced by cloud services like iCloud Drive, OneDrive, or Dropbox, the sync client may lock these temporary scratch files mid-write, leaving orphaned .crswap files behind. These files hold no final state and can be safely deleted at any time. Placing your library in its own dedicated folder keeps any temporary files neatly isolated.
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.
Safari Local File Sync Bridge (Fallback for Non-Chromium Browsers): When the browser supports the native File System Access API (Chrome, Edge, Brave), Brain reads and writes directly to your local .json file. When window.showOpenFilePicker is unavailable (such as in Safari), Brain automatically activates a local file bridge client (127.0.0.1:8765) paired with a one-time downloadable macOS setup archive (Enable-Safari-Sync.zip → Enable-Safari-Sync.command). Running the script installs a lightweight local Python LaunchAgent (~/.alibrain/bridge.py) that provides native macOS file pickers, in-place auto-saving, startup auto-resume, and 3-way external change polling in Safari.
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

The synchronization engine ensures safe, concurrent multi-device usage over folder-sync tools like Dropbox, Google Drive, iCloud, or Syncthing. Rather than blindly overwriting entire files, Brain analyzes granular note timestamps to perform non-destructive merges, preserve simultaneous edits, and prevent accidental data loss.

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 overwrite 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, the workspace reloads and updates the view seamlessly.

3. Entry Types & Taxonomy Solo Filtering

The taxonomy and organization system categorizes your knowledge base into distinct functional entry types alongside multi-dimensional tags, categories, and projects. It provides instant filtering controls, drag-and-drop organization, and solo views to isolate specific subsets of notes rapidly.

Notes • Manual User Thoughts Txt • Dropped & Imported Text Seeds • AI Prompt Shortcuts (Gemini Gems) Prompts • AI Theme Reflection Notes Media • Videos & Audio (YouTube/Vimeo) Web • Scraped Web Pages, Articles & PDFs AI Chat • Archived AI Conversations

Core Filtering & Taxonomy Capabilities:

• Type Toggle: Click any entry type badge to toggle that type on or off in the list. Note that AI Chat is hidden by default to keep your note list uncluttered.

• Solo Filtering: Shift + Click any type to solo it — hiding all other types in a single click. Shift-clicking the active solo type again restores all default types.

• Multi-Dimensional Taxonomy: Filter notes by Projects, Categories, and Tags. Drag notes directly onto taxonomy items in the sidebar to assign them instantly.

• Taxonomy Management: Hover over any project, category, or tag in the sidebar to reveal a delete button that removes the taxonomy across all notes in the database.

• Pinning: Pin essential notes to keep them anchored at the top of the list for fast reference.

• Fast Search & Clear: Real-time text search filters across titles and note contents. An inline clear button and Escape shortcut instantly reset your query.

• Sort Toggle: A toggle at the top right of the entry list switches between date created and date modified order (newest first). Pinned notes always stay on top.

• Type-Colored Interface: The reader, editor and Focus Mode accent color follows the entry's type (Note amber, Txt grey, Media red, Web sky, Prompt green, AI Chat purple, Seed blue).

• Taxonomy & Entry-Type Separation: AI taxonomy generation and auto-tagging strictly separate structural document formats (notes, txt, media, web, prompts, ai chat) from domain topics to keep your taxonomy clean.

4. Inline Editing & Field Generators

The document editor delivers a seamless, in-place writing and curation workflow. Every individual component of a note can be edited directly without opening separate modal forms, while dedicated AI action triggers allow you to selectively regenerate or refine specific fields on demand.

Double-Click Inline Editing

Double-click any field — Title, Executive Summary, Answer Summary, or Takeaways — to edit it directly in place. Edits commit automatically on blur or Enter.

Targeted Field Generators & Auto-Metadata

Independent refresh buttons beside each section trigger Gemini AI to re-extract or suggest content for only that specific field (Title, Taxonomy, Summary, or Key Takeaways) without affecting the rest of the document. When a user saves a note's content edit for the first time (via Done, clicking outside, or exiting Focus Mode), the system automatically synthesizes all metadata fields in a single pass—generating a descriptive title (if untitled), an executive summary, key takeaways, and contextual domain taxonomies (projects, categories, and tags) together.

Unified Instruction Registry (Single Source of Truth): Both targeted individual field generators and the combined initial auto-generation pipeline share a canonical, DRY instruction registry (METADATA_FIELD_SPECS). Dynamic prompt construction, schema definitions, and sanitizers are maintained in one place, ensuring 100% prompt consistency and zero behavioral drift between single-field and multi-field synthesis.

In-Place Taxonomy Editor

Clicking the taxonomy badges in the note header opens an inline manager to add new tags, remove existing tags, or trigger AI auto-tagging.

Distraction-Free Focus Mode

Double-clicking note content or clicking Edit opens an inline textarea editor with a flush-right Edit button (which becomes Done while editing) and a Focus Mode button that appears only while editing. Activating Focus Mode launches a centered distraction-free writing window. Exiting Focus Mode (via Esc, backdrop click, or close button) returns to the inline editor without saving or ending editing; click Done (or press Esc in the inline editor) to save.

Workspace State Persistence: The open/collapsed states of sidebars and panels are persisted into your workspace file and restored automatically across sessions.

5. Content Ingestion & Media Scrubbing

The ingestion pipeline transforms raw web links, multimedia URLs, and pasted text into clean, structured knowledge entries. Ingested content is automatically sanitized, formatted into Markdown, and enriched with AI-generated metadata.

Web Article Scraping: Strips navigation bars, advertisements, cookie notices, and scripts using turndown to capture clean article text and formatting.
Media Embedding: Automatically recognizes YouTube and Vimeo links to embed a responsive media player alongside synchronized note-taking capabilities.
Direct Substance Metadata Extraction: When a user finishes editing a note for the first time, Gemini AI automatically synthesizes all metadata fields together in one pass: a concise title (if untitled), a substantive executive summary (1–2 informative sentences articulating context, core arguments, and takeaways without throat-clearing preambles), 3–5 insightful key takeaways, and contextual domain taxonomies (projects, categories, and tags). Supported by a 4,096-token output budget and multi-layer extraction fallbacks to guarantee uninterrupted completion across reasoning models (Gemini 2.5 Flash / Pro).

6. Gemini AI Synthesis & Theme Prompt Generator

The Theme Prompt Generator analyzes your notes to surface connections, contradictions, and open questions that prompt new reflection notes.

Filter-Scoped Candidate Pool: Draws with equal weight from whatever notes are currently visible in your list (based on active Entry Types, Projects, Categories, Tags, and Search filters) that have an Executive Summary or Key Takeaways.

Theme Prompt Pool Settings (in General Settings): Configured inside the Settings modal () under Theme Prompt Pool Settings:

Date Range (dateRangeMonths): Defaults to 2 months (adjustable from 1 to 24 months, or All Time). Restricts the pool to notes created or updated within that timeframe.
Pool Size (poolSize): Defaults to 10 notes (adjustable from 5 to 50 in steps of 5, with the final step set to All). Controls how many eligible notes are randomly sampled (or all sent when set to All) in the request.

Single-Pass Synthesis & In-Place Refresh: Sends only the Title, Date, Executive Summary, and Key Takeaways of the sampled notes in a single API call. The model isolates one specific idea from 1 or 2 notes, links them with [[kb-ref:ID]] citations, and asks one open-ended "Why" or "How" reflection question (capped at 50 words). A refresh icon (fa-rotate-right) sits next to the Write button on generated prompt cards to roll a new prompt in place without dismissing first.

Model & Default Temperature (1.0): Uses the Theme Prompts model configured in Settings (taskModels.prompts) with a fixed default temperature of 1.0 (Google's recommended default for Gemini 2.5 reasoning models and associative synthesis across disparate ideas).

Knowledge Provenance & User Perspective: Prompts strictly assume only manual Notes and Prompt replies represent user-generated content reflecting their own issues, projects, and personal knowledge. Web, media, and text documents are treated as external and contextual third-hand knowledge (articles, videos, secondary research). Seeds and AI chats are ignored.

Animated Top Placement Above Search Bar: When generated, theme prompts smoothly expand between the entry creation buttons and the search bar, transitioning the search bar and note cards downward. Dismissing or saving the prompt smoothly glides the list layout back into position.

7. Unified AI Assistant & Chat Modes

The AI Assistant lets you chat with either a single open note or your broader knowledge base.

Current Entry Chat (Right Drawer):
- Conversational Synthesis & Active Note Discussion: Discussions, brainstorming, questions, and feedback remain strictly within the chat conversation. The assistant has direct access to the active document's full content and context, answering queries without modifying user documents. When discussing the active note, circular self-references are suppressed so links remain clean and valid.
- Context & On-Demand Cross-Note Content: Sends the active note's full Content field (including live staged editor text), summary, takeaways, and source URL (as well as its reflection question for Prompt entries). Other notes across your knowledge base are summarized with on-demand availability; the assistant dynamically requests and inspects the full Content fields of other notes in a second pass whenever cross-document comparison, reference verification, or multi-note synthesis is needed.
- Auto-Close & Auto-Reopen: Switching notes automatically closes the drawer if the new note has no prior chat, and automatically re-opens it if the note already has a saved conversation (assistantChats[entry.id]). Toggle manually anytime with Cmd+J / Ctrl+J.
Whole Brain / Scoped AI Chat (Full-Width Purple View):
- Dynamic Scope, Inline Editing & Auto-Generated Titles: Named automatically after your active Entry Type and Taxonomy filters (e.g., Whole Brain AI Chat or Project: X AI Chat), with double-click inline editing and automatic title generation once the first AI response arrives, distilling the conversation into a concise 3–6 word title.
- Persistent Executive Summary Field & Auto-Generation: Global AI chat sessions feature a persistent, directly editable Executive Summary section with an on-demand "Generate" button. Navigating or clicking out of an AI chat automatically generates an AI summary in the background if left unsummarized, which also displays as the entry preview in sidebar cards.
- Uncapped Summaries First, Details On Demand: Sends all matching note Executive Summaries (summary) with no artificial count limit—you control the scope via your type and taxonomy selections. If summaries are enough to answer, the AI replies in a single pass (directReply). If deeper detail is required, it automatically fetches Key Takeaways (takeawayIds) or Full Content (contentIds) for specific notes in a second pass.
- Auto-Selected Type & Excluded Prior Chats: Clicking the purple Chat / New Chat button automatically enables the AI Chat entry type in the list so your chat sessions are visible, while strictly excluding previous AI Chat entries from being fed into context for new chats.
- Persistent & Self-Cleaning: Conversations save automatically to their AI Chat entry and resume when clicked. Empty chats that you navigate away from without sending a message are pruned automatically.
- In-Place Taxonomy Editing: An interactive taxonomy row sits directly under the metadata subtitle, allowing you to click and open the standard taxonomy editor to assign or remove Projects, Categories, and Tags (or auto-generate tags) for the chat session.
Cumulative AI Token Tracking (Out / In): Both AI Chat views display a live Tokens Out: X | In: Y counter at the top of the chat header, representing the application's perspective: tracking cumulative prompt tokens sent out to the model (inputTokens → Out) and response tokens arriving into the app (outputTokens → In) across every turn of the conversation (including two-pass context escalations).
Response Style & Temperature (0.3): Uses a focused temperature of 0.3 for factual accuracy, plain conversational English, a 50-word default target (100-word ceiling unless asked for detail), and inline [[kb-ref:ID]] source citations.
Knowledge Provenance Grounding & Prompt Questions: In both Current Entry and Whole Brain chat modes, the AI strictly assumes only Notes and Prompt replies are user-generated content reflecting personal thinking, projects, and issues. For Theme Prompt entries, the reflection question is automatically supplied to the model alongside the user's answer so discussions remain grounded on the original question. Web, Media, and Text documents provide external third-hand context, while Seeds and prior AI chats are never used as knowledge context.
On-Demand Web Search Policy: By default, the AI assistant focuses strictly on synthesizing the user's local knowledge base library and does not perform web searches. When the user explicitly requests to look outside of the library or specifically requests a web search (e.g., "search the web", "look online", "search outside my library"), the app activates live Google Search grounding (tools: [{ google_search: {} }]), synthesizes up-to-date web results with clickable source links, and ensures the assistant never erroneously claims it is unable to perform web searches.

8. Backlinks & Decimal Numeric IDs

Ali Brain implements a lightweight, bi-directional referencing and linking network. You can connect ideas across different documents seamlessly without relying on proprietary database graph structures or fragile absolute paths.

Interactive Backlinks & Citations: Using [Ref: 23] (or lowercase [ref: 23], as well as legacy [[kb-ref:ENTRY_ID]]) establishes an interactive link matching the rendered display format directly. Hovering over the reference renders an instant summary popover, while clicking navigates directly to the referenced note.
External Links Open in New Tab: All web URLs and markdown links across note contents, markdown previews, prompt responses, and AI chat messages automatically open in a new browser tab (target="_blank" rel="noopener noreferrer"), keeping your active workspace open and undisturbed.
Drag to Reference: Drag any note card from the sidebar list and drop it into the Markdown editor to automatically insert a clean [Ref: ID] reference link.
Chronological Decimal IDs: Notes use stable decimal identifiers (e.g. #1, #2, #2.1), permitting chronological insertions into intermediate timeline gaps while maintaining stable referencing.

9. Settings & Workspace Management

Workspace settings give you comprehensive control over AI configuration, model assignments, API key rotation, and multi-file merges. All settings are stored locally within your browser and knowledge base file.

API Key Management: Store and rotate multiple Google Gemini API keys to distribute usage across quotas.
Task-Specific Model Assignment: Assign distinct Gemini models optimized for specific task categories:
- Metadata & Summaries: High-speed models (e.g. gemini-flash-lite-latest) for fast titles, takeaways, and auto-tagging.
- Theme Prompts: High-reasoning models for synthesizing loose ends and generating reflection questions.
- AI Assistant Copilot: Interactive models for contextual chatting and knowledge-base synthesis.
AI Instructions & User Context: Fine-tune instructions and inject personal profile context:
- User Context: Background information, ongoing research/projects, and style preferences prepended into prompt and chat syntheses.
- Theme Prompts: Customizable rules controlling tension exploration, concept isolation, question style, and word limits with one-click reset to default.
- AI Chat Rules: Conversational rules, knowledge provenance assumptions, and style constraints for both Whole Brain and Single-Entry chats with one-click reset to default.
- Deterministic Metadata: Extraction rules for titles, summaries, and takeaways remain fixed for consistent cataloging.
Install as App (PWA): The Install as App section in Settings installs Ali Brain as a standalone app (Install button in Chrome/Edge; File > Add to Dock in Safari on macOS) and shows offline-cache status. A service worker caches the app files and CDN libraries so the app launches offline (AI calls and the Safari sync bridge are never cached; the offline cache needs the app served over http/https). Safari still needs the Local Sync Bridge to read and write your notes file.
Live Model Discovery: Dynamically fetch available models directly from Google AI Studio to select the latest versions and experimental releases.
Workspace Merging & Text File Import: Merge secondary JSON knowledge bases or import multiple plain text (.txt) and Markdown (.md) files directly into your active workspace. Imported text files preserve their original file modification and creation timestamps (createdAt and updatedAt), name notes after the filename, and automatically generate executive summaries with Gemini. Multiple files can be selected simultaneously.

10. Keyboard Shortcuts & Gestures

Ali Brain is optimized for high-speed, keyboard-driven navigation, writing, and curation. Use these global shortcuts, editor keybindings, and gesture modifiers to navigate your knowledge base seamlessly without reaching for the mouse.

Global Navigation & Workspace Controls

Shortcut	Action
`Alt` + `←` / `Cmd` + `[` / `Ctrl` + `[`	Navigate backward in note selection history (triggers the floating on-screen Back button directly).
`Alt` + `→` / `Cmd` + `]` / `Ctrl` + `]`	Navigate forward in note selection history (triggers the floating on-screen Forward button directly).
`Cmd` + `Z` / `Ctrl` + `Z`	Undo note modification or deletion (active outside text input fields).
`Cmd` + `Shift` + `Z` / `Ctrl` + `Shift` + `Z` / `Ctrl` + `Y`	Redo previously undone note modification or deletion (active outside text input fields).
`Cmd` + `J` / `Cmd` + `L` / `Ctrl` + `J`	Toggle the contextual AI Assistant drawer for the active note (bypassed in Whole Brain chat mode).

Note Editing & Focus Mode

Shortcut	Action
`Escape`	In Focus Mode: return to the inline editor (keeps editing). In the inline editor: commits and saves changes immediately, triggers background metadata synthesis, and restores rendered Markdown view.
`Tab`	Insert 2 spaces for text indentation inside note editor textarea without moving focus.
`Enter`	Confirm and commit single-line inline edit fields (Title, Summary, Takeaway). In taxonomy inputs (Projects, Categories, Tags), commits the entered item.
`,` (Comma)	In taxonomy input fields, immediately adds the typed tag, project, or category.
`Escape`	In single-line inline edit fields, cancels editing and reverts to previous text.

AI Conversations & Search

Shortcut	Action
`Enter`	Submit message to AI (in both Whole Brain full-width chat and Current Entry assistant drawer).
`Shift` + `Enter`	Insert newline in AI chat input boxes without submitting.
`Escape`	When search bar is focused with an active query, clears the search text and resets the notes list.

Mouse & Click Modifiers

Gesture / Modifier	Action
Right-Click / Secondary Click Entry Card	Opens desktop context menu with quick options to Copy Reference (`[Ref: ID]`), Pin / Unpin Note, and Delete Note.
`Shift` + Click Entry Type	Solo Filter: Instantly isolates that specific entry type (Notes, Prompts, Media, Web, AI Chat), hiding all others. Shift-clicking the active solo type restores all default types.
`Cmd` / `Ctrl` + Click Note	Toggle multi-selection of notes in the sidebar list.
`Cmd` / `Ctrl` + Click Taxonomy	Multi-select projects, categories, or tags in the sidebar to view notes matching multiple taxonomy filters.
Drag Note → Editor	Drag any note card from the sidebar list into the editor to insert a bi-directional reference link (`[[kb-ref:ID]]`).
Drag Note → Taxonomy	Drag note cards onto any sidebar project, category, or tag to assign taxonomy immediately.
Double-Click Text Field	Initiate inline editing directly on note titles, summaries, or content body.