[![Build Status][build-image]][build-url]

A local-first memory 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 - crate of the week 482 - memories, bookmarks, snippets, etc, searchable, executable.

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

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

• e.g. memories, bookmarks, links, snippets in database
• large documents or scripts in filesystem, references go into database

Both options provide the full management capability of bkmr.

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

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

• 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

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

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