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.1
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.1.tar.gz | 439.3 kB | Details |
Built distributions (wheels)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| bkmr-7.7.1-py3-none-manylinux_2_39_x86_64.whl | Python 3 | none | Linux glibc 2.39+ x86-64 | Details |
| bkmr-7.7.1-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.1.tar.gz
| Download URL | bkmr-7.7.1.tar.gz |
|---|---|
| Size | 439.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
28b5c0f001b77f1294df21a6f18d7f9b88c8dbd5e0464239a4bd5f6f7d9077ab
|
|
BLAKE2b-256 checksum How to use checksums |
569b252b4a5d469671f26eca2432a3bec63edc7c5bd5da62de4e846591489698
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
maturin/1.15.0
|
Release files / bkmr-7.7.1-py3-none-manylinux_2_39_x86_64.whl
| Download URL | bkmr-7.7.1-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 |
9367cdeb1ff83389bdc74653c82bd410d43d4f9c8a7b0bde6f1a392b3320319a
|
|
BLAKE2b-256 checksum How to use checksums |
e8e06c14ada475f2f53e4135b3775b438eb80fb507043f5a64895e0330f5096e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
maturin/1.15.0
|
Release files / bkmr-7.7.1-py3-none-macosx_11_0_arm64.whl
| Download URL | bkmr-7.7.1-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 |
2d7ddb15f86f3143661e725405df0449e58e9307e66094807dd470b30328b27f
|
|
BLAKE2b-256 checksum How to use checksums |
6ad28b8c9f22537b45f2c779c169fbf31ee49c8bd81302584e2766cc7fef4603
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
maturin/1.15.0
|
