Link Brain

Your personal bookmark graveyard, except things actually come back.

Quick Start

python3 scripts/brain.py quickstart           # auto-imports browser bookmarks + opens GUI
python3 scripts/brain.py save "https://example.com" --auto
python3 scripts/brain.py search "that article about sqlite"

First Run

On first run, use quickstart instead of setup. It:

Creates the database
Scans Chrome, Safari, and Firefox for bookmarks
Imports everything it finds (skips duplicates)
Generates the visual GUI console
Returns JSON with import stats

setup also detects browsers and reports what it finds, but doesn't auto-import. Use quickstart when the user wants the fastest path to a working knowledge base.

What It Does

Saves URLs with titles, summaries, tags, and metadata
Full-text search with natural language filters
Auto-fetches and summarizes pages locally (no API keys)
Spaced repetition so your saved links don't rot
Collections for organizing reading lists
Knowledge graph visualization
Reading stats, streaks, and weekly digests
Imports from Chrome, Safari, Firefox, Pocket, YouTube, Reddit
Everything in SQLite. Everything on disk. No accounts. No telemetry.

Data lives in ~/.link-brain/. Override with LINK_BRAIN_DIR=/your/path.

Saving Links

Manual

You know the title. You know what it's about. Just tell it.

python3 scripts/brain.py save "https://docs.python.org" \
  --title "Python docs" \
  --summary "Standard library reference." \
  --tags "python, docs"

Auto

Point it at a URL. It fetches the page, extracts readable text, generates a summary, and suggests tags based on your existing collection. No LLM needed.

python3 scripts/brain.py auto-save "https://example.com"

Or equivalently:

python3 scripts/brain.py save "https://example.com" --auto

This is the only command that makes a network request. Everything else is local.

Finding Stuff

Search

SQLite FTS5 under the hood, but you can write queries like a person.

python3 scripts/brain.py search "last week unread from github"
python3 scripts/brain.py search "best rated rust"
python3 scripts/brain.py search "unrated videos from youtube"
python3 scripts/brain.py search "oldest unread" --limit 10

Tag Suggestions

Get tag ideas for a URL based on your patterns.

python3 scripts/brain.py suggest-tags "https://example.com"

Discovery

When you don't know what to read next.

digest pulls a batch of links for review
recommend surfaces links based on your most-used tags
gems shows your highest-rated links and hidden finds
random grabs something from the backlog

python3 scripts/brain.py digest
python3 scripts/brain.py recommend
python3 scripts/brain.py gems
python3 scripts/brain.py random

Reading Tracking

python3 scripts/brain.py read 42                # mark as read
python3 scripts/brain.py unread                  # show unread links
python3 scripts/brain.py rate 42 5               # rate 1-5
python3 scripts/brain.py streak                  # current streak and activity
python3 scripts/brain.py insights                # reading personality, analytics
python3 scripts/brain.py weekly                  # weekly summary, WhatsApp-ready

streak tracks consecutive days you've read something. insights tells you things like your most active hours and top domains. weekly is a formatted digest you can send straight to a chat.

Collections

Reading lists that reference your saved links.

python3 scripts/brain.py collection create "Rust" --description "Systems stuff"
python3 scripts/brain.py collection add "Rust" 42
python3 scripts/brain.py collection show "Rust"
python3 scripts/brain.py collection list
python3 scripts/brain.py collection remove "Rust" 42
python3 scripts/brain.py collection export "Rust"            # markdown
python3 scripts/brain.py collection export "Rust" --html     # standalone HTML

Review Queue

Spaced repetition for your bookmarks. Every saved link enters the queue. Intervals grow as you review: 1 day, 3 days, 7 days, and so on.

python3 scripts/brain.py review                  # next due item
python3 scripts/brain.py review done 42          # reviewed, advance interval
python3 scripts/brain.py review skip 42          # not now
python3 scripts/brain.py review reset 42         # back to 1-day interval
python3 scripts/brain.py review stats            # queue overview

Auto-Save

The --auto flag on save (or the auto-save shortcut) handles fetching, summarizing, and tagging in one shot. It uses urllib to grab the page, extracts the readable content, and picks tags that match your existing vocabulary. No external services involved.

Knowledge Graph

python3 scripts/brain.py graph --open

Generates a standalone HTML file at ~/.link-brain/graph.html with an interactive canvas. Links are nodes. Shared tags are edges. No external JS libraries. Just open it in a browser.

GUI Console

python3 scripts/brain.py gui

Opens ~/.link-brain/console.html in your browser. Single self-contained HTML file, nothing external. Includes search, tag cloud, knowledge graph, collections, review queue, reading timeline, and dark/light mode.

Add --no-open to generate without launching.

Importing

Browsers

Pull bookmarks directly:

python3 scripts/brain.py scan chrome
python3 scripts/brain.py scan safari
python3 scripts/brain.py scan firefox

Reads from the browser's local bookmark storage. No export step needed.

Platforms

Import from exported files:

python3 scripts/brain.py import pocket_export.html
python3 scripts/brain.py import youtube_history.json
python3 scripts/brain.py import reddit_saved.csv

How to get your exports:

Pocket: Go to getpocket.com/export. You'll get an HTML file.
YouTube: Use Google Takeout. Select YouTube, then pick watch history. You'll get a JSON file.
Reddit: Go to reddit.com/prefs/data-request or old.reddit.com and export saved posts.

Syncing

Check for bookmarks that have been removed from a browser source:

python3 scripts/brain.py sync chrome
python3 scripts/brain.py sources              # see connected sources and sync status

Feedback

python3 scripts/brain.py feedback "your message"
python3 scripts/brain.py feedback --bug "something broke"
python3 scripts/brain.py feedback --idea "wouldn't it be cool if..."
python3 scripts/brain.py debug                # system info for bug reports

Config

All data is stored in ~/.link-brain/:

brain.db (SQLite database)
graph.html (knowledge graph output)
console.html (GUI console)
collection-*.md and collection-*.html (exported collections)

Override the directory:

LINK_BRAIN_DIR=/tmp/test-brain python3 scripts/brain.py setup

Tips

search understands time filters like "last week" and reading states like "unread" or "best rated"
Use --auto on every save unless you have a specific summary in mind. It's fast and surprisingly good.
review stats tells you how many links are overdue. Check it weekly.
gems is great for rediscovering old links you forgot you loved
Export a collection as HTML to share a reading list with someone
The graph gets more interesting after about 50 links. Before that, it's a bit lonely.
random is the "I'm bored" button
Combine scan with sync to keep browser bookmarks in check

link-brain

Safety Notice

Copy this and send it to your AI assistant to learn