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,--stdoutfor 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
The LSP server does one job: Putting _snip_ bookmarks into the editor's completion list.
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-copyfromwl-clipboardpackage - X11: Uses
xclip(preferred) orxselas fallback - Auto-detection: Detects display server via
WAYLAND_DISPLAYenvironment variable
Development
Building from Source
git clone https://github.com/sysid/bkmr.git
cd bkmr
cargo build --release
Running Tests
make test
See TESTING.md for everything test-related: automated, scenario and manual editor tests.
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
1 maintainer
Metadata
1 maintainer
Release files for bkmr 7.7.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| bkmr-7.7.0.tar.gz | 436.8 kB | Details |
Built distributions (wheels)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| bkmr-7.7.0-py3-none-manylinux_2_39_x86_64.whl | Python 3 | none | Linux glibc 2.39+ x86-64 | Details |
| bkmr-7.7.0-py3-none-macosx_11_0_arm64.whl | Python 3 | none | macOS 11.0+ ARM64 | Details |
Total release size: 37.4 MB
Release files / bkmr-7.7.0.tar.gz
| Download URL | bkmr-7.7.0.tar.gz |
|---|---|
| Size | 436.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
99a627a3a1ff7306f769a6a2ca21491a116185ba0a09d423a0bc4f9b4dd10622
|
|
BLAKE2b-256 checksum How to use checksums |
39996c38c3a458686a6e72151802d747df6d38389f892f4714f07fbeb0cf82d6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
maturin/1.15.0
|
Release files / bkmr-7.7.0-py3-none-manylinux_2_39_x86_64.whl
| Download URL | bkmr-7.7.0-py3-none-manylinux_2_39_x86_64.whl |
|---|---|
| Size | 19.8 MB |
| Tags | Linux glibc 2.39+ x86-64 Python 3 |
|
SHA-256 checksum How to use checksums |
a810f69721815266c9852980775c3ea2d7a8b77ea44f8e900722999c6798cf9a
|
|
BLAKE2b-256 checksum How to use checksums |
a86892833c87382a46f04fd32bee4d82e70b7d7686ec7e5b608026c0fbc85f27
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
maturin/1.15.0
|
Release files / bkmr-7.7.0-py3-none-macosx_11_0_arm64.whl
| Download URL | bkmr-7.7.0-py3-none-macosx_11_0_arm64.whl |
|---|---|
| Size | 17.1 MB |
| Tags | Python 3 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
b6b72810861a68c793a34497b712be2fb366fb729052eb26a08c5b4a8c01f11a
|
|
BLAKE2b-256 checksum How to use checksums |
bb07bb9d090c749cd820d5c7eb03a8023b78c96f6288720f16d1826a4f023c1a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
maturin/1.15.0
|
