Store anything, find it by meaning, act on it instantly.

Beyond Bookmarks and Snippets: Knowledge Management for Humans and Agents

bkmr - crate of the week 482 - memories, bookmarks, snippets, text - search it, invoke it!

Organize, find, and apply 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

Why bkmr?

• Developer- and agent-focused: Integrates seamlessly with workflow and toolchain
• Agent-friendly: JSON output, non-interactive mode, and _mem_ system tag for AI agent memory
• 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
• Automation-ready: Programmatic CLI with --json, --np, --stdout for pipelines and integrations
• Editor Integration: Built-in LSP server

Agent Memory and Skill

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 skill/bkmr-memory. It defines a comprehensive memory protocol with taxonomy, deduplication, and session workflows.

See Agent Integration.

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

General Usage:

Fuzzy Search with FZF:

Agent Memory:

Detailed walkthroughs: Overview | Getting Started | Search and Filter | Edit and Update | Tag Management

Getting Started

Installation

# Via cargo
cargo install bkmr

# Via pip/pipx/uv
pip install bkmr

# Via brew
brew install bkmr
export ORT_DYLIB_PATH=/opt/homebrew/lib/libonnxruntime.dylib

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
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

• Home - Wiki overview and navigation
• Quick Start - 5-minute introduction
• Installation - Installation methods and troubleshooting
• Core Concepts - Understanding tags, system tags, and bookmarks

Core Features

• Basic Usage - Common daily operations
• Search and Discovery - FTS, tags, fuzzy finder, semantic search
• Content Types - URLs, snippets, shell scripts, markdown, environment variables
• Shell Scripts - Interactive execution and shell function stubs

Advanced Topics

• Configuration - Complete configuration reference
• Template Interpolation - Jinja2 dynamic content
• Agent Integration - AI agent memory, JSON API, bulk import
• File Import and Editing - Frontmatter, base paths, smart editing
• Semantic Search - Local offline semantic search with fastembed
• Editor Integration - LSP server and editor plugins
• Advanced Workflows - Power user techniques

Reference

• Troubleshooting - Common issues and solutions
• Development - Contributing and building from source

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:

• GitHub: https://github.com/sysid/bkmr
• Issues: https://github.com/sysid/bkmr/issues
• Wiki: https://github.com/sysid/bkmr/wiki
• Discussions: https://github.com/sysid/bkmr/discussions