bkmr 7.4.1

Knowledge management for humans and agents — bookmarks, snippets, etc, searchable, executable.
Documentation

Crates.io Crates.io Docs.rs Build Status

A local-first knowledge base for humans and AI agents. Store anything, find it by meaning, act on it instantly.

Beyond Bookmarks and Snippets: Knowledge Management for Humans and Agents

bkmr reborn

bkmr - crate of the week 482 - is a fast, feature-rich command-line tool that handles bookmarks, snippets, markdown files, scripts and more and adds powerful search.

Organize, find, and apply your various content types:

  • Web URLs with automatic metadata extraction
  • Code snippets for quick access and reuse
  • Shell commands with immediate execution capabilities
  • Markdown documents with live rendering, incl. TOC
  • Plain text with Jinja template interpolation
  • Local files and directories integration
  • Semantic embeddings for local offline search (no API keys needed)

Centralize your data in bkmr's database (add) or keep it in your filesystem (import-files) (see).

  • bookmarks, links short snippets go into the database
  • large markdown documents or scripts stay where they are and references go into database

Both options provide the full benefits of bkmr.

Why bkmr?

  • Developer-focused: Integrates seamlessly with your workflow and toolchain
  • Multifunctional: Handles many content types with context-aware actions
  • Intelligent: Full-text and semantic search capabilities
  • Privacy-focused: Fully local — database, embeddings, and search all run offline
  • Fast: 20x faster than similar Python tools
  • Agent-friendly: JSON output, non-interactive mode, and _mem_ system tag for AI agent memory
  • Automation-ready: Programmatic CLI with --json, --np, --stdout for pipelines and integrations

Editor Integration:

  • Built-in LSP server: Use bkmr lsp for VS Code, Vim, Emacs - automatic snippet completion with language-aware filtering
  • Neovim Plugin: Visual interface with Telescope integration and zero configuration
  • IntelliJ Plugin: JetBrains Marketplace plugin for all IDEs

NEW: Agent Memory

Persistent long-term memory for AI agents. The _mem_ system tag and hsearch (hybrid FTS + semantic search) create a complete read/write memory interface:

# Agent stores memory:
bkmr add "Prod DB is PostgreSQL 15 on port 5433" fact,database \
  --title "Production database config" -t mem --no-web

# Agent queries memories with natural language (hybrid search)
bkmr hsearch "database configuration" -t _mem_ --json --np

# All output is structured JSON — designed for programmatic consumption

Use ready-made skill/bkmr-memory. It defines a complete memory protocol with taxonomy, deduplication, and session workflows.

See Agent Integration for complete documentation.

Quick Examples

# Quick fuzzy search with interactive selection
bkmr search --fzf

# Add URL with automatic metadata extraction
bkmr add https://example.com tag1,tag2

# Store code snippet
bkmr add "SELECT * FROM users" sql,_snip_ --title "User Query"

# Shell script with interactive execution
bkmr add "#!/bin/bash\necho 'Hello'" utils,_shell_ --title "Greeting"

# Render markdown in browser with TOC
bkmr add "# Notes\n## Section 1" docs,_md_ --title "Project Notes"

# Import files with frontmatter
bkmr import-files ~/scripts/ --base-path SCRIPTS_HOME

# Local semantic search (no API keys needed)
bkmr sem-search "containerized application security"

# Agent memory: store and retrieve knowledge
bkmr add "Prod DB on port 5433" fact,database --title "Prod DB config" -t mem --no-web
bkmr hsearch "database config" -t _mem_ --json --np

Screenshots

Bookmarks:

Snippets:

Demos:

Getting Started

Installation

# Via cargo
cargo install bkmr

# Via pip/pipx/uv
pip install bkmr

# Via brew
brew install bkmr

See Installation Guide for detailed instructions and troubleshooting.

Initial Setup

# Generate configuration
bkmr --generate-config > ~/.config/bkmr/config.toml

# Create database
bkmr create-db ~/.config/bkmr/bkmr.db

# Optional: Configure location
export BKMR_DB_URL=~/path/to/db

First Use

# Add your first bookmark
bkmr add https://github.com/yourusername/yourrepo github,project

# Search and find
bkmr search github

# Interactive fuzzy search
bkmr search --fzf

Quick Start Guide: See the Quick Start for a 5-minute tutorial.

Command Reference

Command Description
search Full-text search with tag filtering, FZF, JSON output
hsearch Hybrid search: FTS + semantic with RRF fusion
sem-search Semantic search using local embeddings (offline, no API keys)
add Add bookmarks (URLs, snippets, scripts, markdown, env vars)
open Smart action dispatch based on content type
edit Edit bookmarks (smart: opens source file for imports)
update Modify tags and custom openers
delete Delete bookmarks by ID
show Display bookmark details
import-files Import files/directories with frontmatter parsing
tags View tag taxonomy with usage counts
info Show configuration, database path, embedding status
set-embeddable Mark bookmarks for semantic search embedding
backfill Generate missing embeddings
clear-embeddings Clear all embeddings and content hashes
lsp Start LSP server for editor snippet completion
completion Generate shell completions (bash, zsh, fish)
surprise Open random URL bookmarks

Complete command documentation: See Basic Usage for detailed examples.

Smart Content Actions

bkmr intelligently handles different content types with appropriate actions:

Content Type Default Action System Tag
URLs Open in browser (none)
Snippets Copy to clipboard _snip_
Shell Scripts Interactive edit + execute _shell_
Markdown Render in browser with TOC _md_
Environment Variables Print for eval/source _env_
Text Documents Copy to clipboard _imported_
Agent Memory Display to stdout _mem_

Rule: A bookmark can have at most one system tag. Local files without a system tag open with the default application.

Learn more: Content Types | Core Concepts

Documentation

Comprehensive documentation is available in the bkmr Wiki:

Getting Started

Core Features

Advanced Topics

Reference

Editor Integrations

Access your snippets directly within your editor without context switching.

Neovim Plugin (Recommended)

bkmr-nvim provides visual interface with zero configuration.

{
  "sysid/bkmr-nvim",
  dependencies = { "nvim-lua/plenary.nvim" },
  config = function()
    require("bkmr").setup() -- Zero config required!
  end,
}

Features: Visual snippet browser, in-editor editing, automatic LSP setup, custom commands

Built-in LSP Server

Compatible with VS Code, Vim, Emacs, Sublime, and any LSP-compatible editor.

# Start LSP server
bkmr lsp

# Disable template interpolation if needed
bkmr lsp --no-interpolation

Features: Automatic completion, language-aware filtering, universal snippets, template interpolation

IntelliJ Platform Plugin

bkmr-intellij-plugin for all JetBrains IDEs.

Features: Seamless LSP integration, Tab navigation, works in IntelliJ IDEA, PyCharm, WebStorm, CLion, RustRover, and all JetBrains IDEs

Complete documentation: Editor Integration

Platform Compatibility

Linux Clipboard: Uses external tools for reliable clipboard persistence.

  • Wayland: Uses wl-copy from wl-clipboard package
  • X11: Uses xclip (preferred) or xsel as fallback
  • Auto-detection: Detects display server via WAYLAND_DISPLAY environment variable

Development

Building from Source

git clone https://github.com/sysid/bkmr.git
cd bkmr
cargo build --release

Running Tests

IMPORTANT: All tests must be run single-threaded:

# Run tests (REQUIRED: single-threaded)
cargo test -- --test-threads=1

# Or use Makefile
make test

Why single-threaded? Tests share a SQLite database and environment variables. Parallel execution causes race conditions.

See Development for complete contributor guide.

Community and Contributions

We welcome contributions! Please check our Contributing Guidelines to get started.

Resources: