Skip to content

Core Concepts

Jump to bottom
sysid edited this page Apr 8, 2026 · 5 revisions

Core Concepts

Understanding these core concepts will help you use bkmr effectively.

Bookmarks

In bkmr, a bookmark is any piece of content you want to store and retrieve later. The term "bookmark" is used broadly — it covers URLs, code snippets, scripts, documents, and more.

Data Model

┌─────────────────────────────────────────────────────┐
│                     Bookmark                        │
├──────────────┬──────────────────────────────────────┤
│ id           │ Auto-incremented integer             │
│ URL/Content  │ The payload: a URL, code, script,    │
│              │ markdown, or env vars                │
│ Title        │ Human-readable name                  │
│ Description  │ Optional notes/context               │
│ Tags         │ User tags + at most one system tag   │
│ file_path    │ Source file (NULL for regular bkmrs) │
│ open_with    │ Custom opener command (optional)     │
│ embeddable   │ Whether to generate embeddings       │
├──────────────┴──────────────────────────────────────┤
│ FTS5 index   │  vec_bookmarks (embeddings)          │
└─────────────────────────────────────────────────────┘

The Core Workflow

  ADD                    SEARCH                   ACT
  ───                    ──────                   ───
  bkmr add ...    →    bkmr search ...    →    bkmr open <id>
  bkmr import-files     bkmr search --fzf       (action depends on
                        bkmr sem-search          system tag)
                        bkmr hsearch

Tags

Tags are the primary organization mechanism in bkmr.

User Tags

  • Free-form labels you assign
  • Comma-separated, no spaces: python,security,auth
  • Used for filtering and organization
  • Case-sensitive

Examples:

bkmr add <content> python,web,tutorial
bkmr search -t python,security

System Tags

Special tags that determine how bkmr handles content:

System Tag Purpose Default Action
_snip_ Code snippet Copy to clipboard
_shell_ Shell script Interactive edit + execute
_md_ Markdown document Render in browser
_env_ Environment variables Print for sourcing
_imported_ Imported file content Copy to clipboard
_mem_ Agent memory Display content to stdout

Rules:

  • A bookmark can have at most one system tag. Adding a system tag replaces any existing one.
  • System tags are enforced at the domain level — attempting to set two system tags raises an error.

Automatic assignment:

  • Added with --type snip → Gets _snip_ tag
  • Added with --type shell → Gets _shell_ tag
  • Added with -t mem → Gets _mem_ tag
  • Imported .md files → Get _md_ tag

Agent Memory (_mem_): Bookmarks tagged _mem_ print their content to stdout when opened — no browser, no clipboard. Combined with --json and --np flags, this creates a complete read/write memory interface for AI agents. See Agent Integration for patterns.

Content Types

Content types determine how bkmr processes and presents your bookmarks. See Content Types for detailed information.

Common Content Types

1. URLs

bkmr add https://example.com dev,reference
# Opens in browser when accessed

2. Snippets

bkmr add "console.log('test')" javascript,_snip_ --title "Debug Log"
# Copies to clipboard when accessed

3. Shell Scripts

bkmr add "#!/bin/bash\necho 'Hello'" utils,_shell_ --title "Greeting"
# Interactive editor before execution

4. Markdown

bkmr add "# Title\n\n## Section" docs,_md_ --title "Documentation"
# Renders in browser with TOC

Smart Actions

bkmr open is a single command that dispatches to the right action based on the system tag:

                        bkmr open <id>
                              │
                    ┌─────────┴──────────┐
                    │  What system tag?  │
                    └─────────┬──────────┘
          ┌──────┬──────┬─────┼─────┬──────┬──────┐
          ▼      ▼      ▼     ▼     ▼      ▼      ▼
       (none)  _snip_ _shell_ _md_ _env_ _imported_ _mem_
          │      │      │      │     │      │        │
          ▼      ▼      ▼      ▼     ▼      ▼        ▼
        Open   Copy  Edit+   Render Print  Copy    Print
       browser clipbd Execute browser stdout clipbd stdout

# Same command, different actions:
bkmr open <url-id>      # Opens in browser
bkmr open <snippet-id>  # Copies to clipboard
bkmr open <shell-id>    # Interactive editor + execute
bkmr open <md-id>       # Renders in browser with TOC
bkmr open <env-id>      # Prints for eval/source

This context-aware behavior means you don't need different commands for different content types.

Database

bkmr stores everything in a local SQLite database:

  • Default location: ~/.config/bkmr/bkmr.db
  • Configurable via BKMR_DB_URL environment variable
  • Includes full-text search (FTS5) index
  • Semantic embeddings for local offline search (via fastembed + sqlite-vec)

Search Methods

bkmr provides four search engines plus an interactive mode:

┌────────────────────────────────────────────────────────────┐
│                    Search Methods                          │
├──────────┬──────────┬────────────┬─────────────────────────┤
│  search  │sem-search│  hsearch   │  search --fzf           │
│  (FTS5)  │(vectors) │(FTS+sem)   │  (interactive)          │
├──────────┼──────────┼────────────┼─────────────────────────┤
│ Keyword  │ Meaning  │ Both via   │ Any of the above +      │
│ matching │ matching │ RRF fusion │ fuzzy text filtering    │
│ Exact,   │ No API   │ Best of    │ Keyboard shortcuts for  │
│ fast     │ keys     │ both worlds│ open/edit/delete/clone  │
└──────────┴──────────┴────────────┴─────────────────────────┘

1. Full-Text Search (FTS)

bkmr search "python security"
bkmr search "containerization"

2. Tag Filtering (combinable with any search method)

bkmr search -t python,tutorial       # Must have ALL tags (AND)
bkmr search -n python,rust           # Must have ANY tag (OR)
bkmr search -N deprecated,old        # Exclude if has ANY of these tags

3. Fuzzy Finding (Interactive)

bkmr search --fzf                    # Interactive picker
bkmr search --fzf -t python          # Pre-filtered fuzzy search

4. Semantic Search (Local, Offline)

bkmr sem-search "deploy automation"
# Finds conceptually similar content — no API keys needed

5. Hybrid Search (FTS + Semantic combined)

bkmr hsearch "containerized security"
# Runs both engines, merges with Reciprocal Rank Fusion

See Search and Discovery for comprehensive search documentation.

Programmatic access: All search commands support --json for structured output and --np for non-interactive operation. For AI agent integration patterns, see Agent Integration.

File Integration

bkmr can import files with metadata and track changes:

# Import with frontmatter
bkmr import-files ~/scripts/backup.sh

# Smart editing (edits source file)
bkmr edit <imported-id>

See Content Types — File Import for details.

Template Interpolation

Make content dynamic with Jinja2 templates:

# Dynamic date in URL
bkmr add "https://reports.com/{{ current_date | strftime('%Y-%m-%d') }}" reports

# Environment variables in scripts
bkmr add "export PATH={{ env('HOME') }}/bin:\$PATH" env,_env_

See Template Interpolation for details.

Next Steps

bkmr

Getting Started
Using bkmr
Agent Integration
Advanced
Reference

Clone this wiki locally