bkmr-memory skill
A skill that turns the local bkmr bookmark database into long-term agent memory with hybrid search and five record types
- 267 ★ on the repository
- Last commit
- BSD-3-Clause
Extended access
Why this level
- The skill asks the agent to call `bkmr` in the shell every session and write conclusions into the database
- The agent decides what to save, so server names, ports and user habits can land in the local database
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add skills/bkmr-memoryDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- The skill asks the agent to call `bkmr` in the shell every session and write conclusions into the database
- The agent decides what to save, so server names, ports and user habits can land in the local database
This is third-party code. Review the repository files before installing.
What it does
bkmr-memory teaches an agent to keep memory between sessions in a bkmr database instead of `MEMORY.md` files. The skill description says it supersedes built-in file memory: the agent turns to it when asked what it remembers, at the start of a task, before an architectural decision and at the end of work, when findings need saving. The agent reads with one command, `bkmr hsearch "query" -t _mem_ --json --np`. It combines full-text and semantic search and returns JSON with `id`, `url`, `title`, `tags` and an `rrf_score`. Exact phrases and boolean conditions go through `bkmr search`. The agent writes with `bkmr add` and the `-t mem` flag plus exactly one classifying tag: `fact`, `procedure`, `preference`, `episode` or `gotcha`. The memory text lives in the `url` field and must stay under 500 tokens. The title and tags go into the embedding, so the skill asks for descriptive ones. The skill lists what not to store: code snippets, git history, lists of changed files, and anything already in `CLAUDE.md` or readable from source. A project is marked with a `project:name` tag and no duplicate bare tag. bkmr itself is a Rust program: a manager of bookmarks, snippets and notes with local embedding search that works offline. The skill sits in the `skill/bkmr-memory` directory of the repository.
Who it is for. For developers who work with Claude Code or another agent day after day and want it to remember decisions, preferences and pitfalls without cloud services.
Good fit when
- The agent relearns that the production database sits on a non-standard port every time, and you want to record it once
- You need memory that stays off the cloud: the database, embeddings and search all run locally
- You already keep bookmarks, snippets and scripts in bkmr and want the agent to search the same store
- You want to review past debugging: `episode` and `gotcha` records filter separately with the `-n` flag
- Several projects share one database, and records are separated by `project:name` tags
Not a fit when
- You need shared team memory in the cloud: bkmr keeps everything in a local SQLite database
- The machine cannot take a Rust binary, the Python wrapper or the Homebrew package
- Project rules already fit in `CLAUDE.md`: the skill itself advises not to duplicate what is written there
- You need a graph of links between memories: bkmr is a flat store of tagged records
Example request
Remember that in this project migrations run with make migrate from the billing folder. Save it as a procedure with the project:billing tag.Limitations
- The skill needs the bkmr program on PATH: without it the `bkmr hsearch` and `bkmr add` commands fail. Install with `cargo install bkmr`, `pip install bkmr` or `brew install bkmr`.
- After a Homebrew install you must point the `ORT_DYLIB_PATH` variable at the ONNX Runtime library, otherwise semantic search does not work.
- Before first use create the config and database with `bkmr --generate-config` and `bkmr create-db`. The database path is set by the `BKMR_DB_URL` variable.
- The skill overrides the agent's built-in file memory, so earlier `MEMORY.md` entries do not move into it by themselves. Migration is manual.
- One record is limited to 500 tokens, and the `_mem_` tag plus one classifying tag is mandatory, otherwise the record is hard to find.
How to disable. Delete the `bkmr-memory` skill directory from `~/.claude/skills/` or the project's `.claude/skills/` and the agent returns to ordinary memory. Records stay in the bkmr database and can be removed with `bkmr delete`. The program itself is removed by `cargo uninstall bkmr`, `pip uninstall bkmr` or `brew uninstall bkmr`.
FAQ
How do I give Claude Code long-term memory through bkmr?
Install the bkmr program, create a database with `bkmr create-db` and put the `skill/bkmr-memory` directory in `~/.claude/skills/`. The skill then teaches the agent to search memory at the start of a task and record conclusions at the end.
Which record types does the skill distinguish?
Five: `fact` for infrastructure, `procedure` for steps, `preference` for user habits, `episode` for debugging write-ups and `gotcha` for non-obvious pitfalls. Every record gets exactly one such tag.
Does semantic search need the internet?
No. A local model computes embeddings through fastembed and ONNX, and no API keys are needed. Only the Homebrew install requires you to point at the ONNX Runtime library.
How does bkmr-memory differ from a MEMORY.md file?
The skill moves memory into a SQLite database with tags and full-text plus semantic search instead of reading flat files. The agent pulls only matching records through `hsearch` rather than the whole memory.
What does the skill refuse to store?
Code snippets, git history, lists of changed files, temporary state and anything in `CLAUDE.md` or readable from source. Only conclusions missing from the code are saved.
Discussion
No questions or reviews yet.
Related
SkillsLong-term memory for AI agents: a skill and the mindmemos command store facts from conversations and recall them in later sessions
Long-term agent memory in local Markdown files with a link graph, semantic search and MCP access
Shared local memory for AI agents: Claude Code, Codex, Cursor and others find the agreements of past sessions in it and record new ones
A Claude Code skill that pulls memory from Memori Cloud before every non-trivial answer and writes new facts back to it
A long-term memory MCP server for agents: one Rust binary that runs offline and never calls a language model
A long-term memory plugin that keeps decisions, preferences and task state across sessions and injects only what a query needs
Comparison with similar tools
Entries that share the main search query, and how they differ.
| Entry | Official | Repository stars | Main difference |
|---|---|---|---|
| bkmr-memory (this entry) | no | 267 | |
| agent-memory | no | 4,374 | also keeps agent memory on a local index, but Markdown files are the source of truth |
| claude-supermemory | yes | 2,796 | the Supermemory plugin for Claude Code, while here the database and search run on your machine |
README in short
The repository page presents bkmr as a knowledge manager for humans and agents, with quick command examples and tables of commands and content types. The agent memory block points to the `skill/bkmr-memory` skill, and details live in the wiki.
README badge
Original SKILL.md
--- name: bkmr-memory description: > Primary memory system — supersedes built-in file-based memory (MEMORY.md / memory/ directory). All memory reads and writes go through bkmr, not the filesystem. Invoke for ANY of: (1) User asks about memories, past sessions, what you remember — "what do you know about X". (2) User asks to remember or save something for future sessions. (3) Starting a new task — check for relevant context, gotchas, or preferences. (4) Encountered a bug or surprise — check if seen before. (5) Making an architectural or tooling decision — check for prior decisions. (6) End of task — persist non-trivial learnings. When in doubt, invoke — a quick bkmr query costs almost nothing. DO NOT use file-based memory — use bkmr instead. --- # bkmr-memory — Persistent Agent Memory bkmr is a CLI bookmark manager with SQLite FTS5 and local semantic search (fastembed/ONNX). Bookmarks tagged with the `_mem_` system tag serve as persistent agent memory that survives across sessions. This skill defines how to read and write that memory effectively. ## Mandatory Tag Rules Every interaction with bkmr memory requires specific tags. These are non-negotiable — without them, memories are unfindable or uncategorized noise. **READING — every query must include `-t _mem_`:** ```bash bkmr hsearch "query" -t _mem_ --json --np # default: hybrid (FTS + semantic) ``` The `-t _mem_` flag scopes results to agent memories only. Without it, you search the entire bookmark database (personal bookmarks, snippets, shells, etc.) — guaranteed noise. Always use `hsearch` as your search command. It combines FTS and semantic ranking via Reciprocal Rank Fusion, so it handles both keyword and conceptual queries well. Only fall back to `search` (FTS-only) when you specifically need exact phrase matching (`'"JWT expiry"'`), boolean logic (`'auth NOT oauth'`), or tag-only browsing with no query text (`-t _mem_ -n gotcha`). **WRITING — every memory must use `-t mem` AND exactly one classification tag:** ```bash bkmr add "content" "CLASSIFICATION,topic1,topic2" --title "Title" -t mem --no-web # ^^^^^^^^^^^^^^ # REQUIRED: exactly one of: fact, procedure, preference, episode, gotcha ```