link-brain

name	link-brain
version	4.3.0
description	Local knowledge base for links. Save URLs with summaries and tags, search later using natural language, build collections, and review your backlog with spaced repetition. Includes a standalone HTML graph view.

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:

1. Creates the database
2. Scans Chrome, Safari, and Firefox for bookmarks
3. Imports everything it finds (skips duplicates)
4. Generates the visual GUI console
5. 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

Tags

python3 scripts/brain.py tags                    # list all tags
python3 scripts/brain.py tags python             # links tagged "python"

Related

Find links that share tags with a specific one.

python3 scripts/brain.py related 42

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