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 Plat