bkmr-memory

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_ : 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: bkmr add "content" "CLASSIFICATION,topic1,topic2" --title "Title" -t mem --no-web # ^^^^^^^^^^^^^^ # REQUIRED: exactly one of: fact, procedure, preference, episode, gotcha The five classification tags: Tag Use for Example fact Infrastructure truths, config, architecture "Prod DB is PostgreSQL 15 on port 5433" procedure How-to steps, deployment, workarounds "Deploy: make deploy-staging, then verify health" preference User conventions, tool choices, style "User prefers pytest, uses fixtures not setUp" episode Debugging narratives, surprising discoveries "2026-04-04: JWT expiry was 5s not 5m" gotcha Non-obvious pitfalls, things that broke "CI silently succeeds when registry is down" A memory without a classification tag cannot be filtered by category — it becomes a second-class citizen in search results and breaks the taxonomy that makes memory useful. Optional Tag Rules You may use topic tags for additional classification (e.g., database , postgres , deployment , auth ). To limit scope to a project, you may use a project tag. MANDATORY STRUCTURE for project tag: project:foo . No redundant tags. If you use a project tag project:foo , do NOT also add a bare foo tag — project:foo already carries the project identity. Same rule for any topic expressed as both a namespaced and bare tag (e.g., don't pair lang:python with python ). Pick the more specific form and drop the other. Redundant tags dilute embedding signal and waste the 2–4 topic-tag budget. Topic tags should name the subject matter (e.g., fzf , skim , bash ), not repeat the project. How It Works A memory bookmark has three meaningful fields: Field Purpose Limit url The memory content (what you're storing) max. 500 tokens title A concise, searchable title Short phrase tags Classification + topic tags Comma-separated The url field IS the memory. This is the first positional argument to bkmr add . Do NOT put memory content in the -d (description) field — that field is not used for embeddings or the memory display action. If you put content in description instead of url, the memory becomes unsearchable and displays as empty. Keep memories concise. Embeddings for semantic search are computed from content (url) + title + visible tags (system tags like _mem_ are excluded from embeddings). This means your title and tags directly affect how well the memory is found — make them descriptive. 1. Querying Memories (READ) When to Query At every task start — before doing any work, check for relevant memories Before architectural decisions — check for gotchas, preferences, procedures When something feels familiar — "didn't we solve this before?" When encountering a bug or surprise — check for past episodes or gotchas How to Query Use one hsearch call per lookup. Do not run both hsearch and search for the same query — the results overlap heavily and waste context. # Standard query — handles keywords and conceptual matches bkmr hsearch "database connection pooling" -t _mem_ --json --np # With a classification filter — narrows results to a category bkmr hsearch "deployment steps" -t _mem_ -n procedure --json --np # Limit results when you only need top matches bkmr hsearch "auth middleware" -t _mem_ --json --np -l 5 FTS-only fallback — use search instead of hsearch only for these three cases: # 1. Exact phrase match (quotes inside the query) bkmr search '"JWT expiry"' -t _mem_ --json --np # 2. Boolean logic (AND/OR/NOT) bkmr search 'auth NOT oauth' -t _mem_ --json --np # 3. Tag-only browse with no query text bkmr search -t _mem_ -n gotcha --json --np Reading the Results hsearch --json returns: [ { "id" : 42 , "url" : "The auth service uses JWT with 24h expiry. Refresh tokens are stored in Redis, not the DB." , "title" : "Auth token architecture" , "tags" : ",_mem_,fact,auth," , "rrf_score" : 0.032 } ] The url field contains the actual memory content. The rrf_score indicates relevance — higher is better. Use id to reference a specific memory for updates. To view a single memory in detail: bkmr show 42 --json Note: search --json returns a slightly different shape (tags as array, includes access_count / created_at / updated_at instead of rrf_score ), but the key fields ( id , url , title , tags ) are the same. Query Patterns by Situation Situation Query Starting work on a project bkmr hsearch "project-name overview" -t _mem_ --json --np -l 10 Before changing architecture bkmr hsearch "architecture decisions" -t _mem_ -n gotcha --json --np Checking user preferences bkmr hsearch "conventions style" -t _mem_ -n preference --json --np Recalling a past debugging session bkmr hsearch "debugged auth issue" -t _mem_ -n episode --json --np Looking up a deployment procedure bkmr hsearch "deploy staging" -t _mem_ -n procedure --json --np Browse all gotchas (no query) bkmr search -t _mem_ -n gotcha --json --np 2. Storing Memories (WRITE) When to Store Before completing any task, ask yourself: Did I learn anything non-trivial about this project, codebase, user preferences, or environment that would be valuable in a future session? Store it if the insight is: Not derivable from reading source code or git history Not already in documentation (README, CLAUDE.md, comments) Likely to save time or prevent mistakes in a future session A user preference, convention, or decision rationale Do NOT store: Code snippets (reference the file path instead) Anything already in CLAUDE.md or project docs Git history facts ( git log is authoritative) Obvious things ("this project uses Rust" — the Cargo.toml says that) Temporary state or in-progress work details Full file contents or large artifacts What you changed — file lists, renames, refactoring summaries, documentation updates. All of this is recoverable from git log , git diff , and reading the code. A memory that says "Updated files X, Y, Z" or "Renamed A to B" is pure noise. Anything derivable by reading the codebase — project structure, which classes exist, what frameworks are used, how modules are wired together. The code is the source of truth; re-reading it is cheap. Only store interpretations that aren't obvious from the code (e.g., "X looks wrong but is intentional because of Y constraint"). Memory Taxonomy Every memory gets exactly one classification tag: Tag Use for Content style fact Truths about infrastructure, config, architecture Short declarative statement procedure How-to sequences, deployment steps, workarounds Numbered steps or command sequence preference User conventions, tool choices, style decisions "User prefers X over Y because Z" episode Debugging narratives, surprising discoveries, non-obvious decisions "On DATE, X failed because Y (non-obvious). Fix was Z." gotcha Non-obvious pitfalls, footguns, things that broke before "X looks like it should work but fails because Y" How to Store bkmr add "CONTENT" "CLASSIFICATION,TOPIC_TAGS" --title "TITLE" -t mem --no-web Concrete examples: # Fact bkmr add \ "Production PostgreSQL 15 runs on db-prod-1.internal:5433. Read replicas on ports 5434-5436. Connection pool max is 50." \ "fact,infrastructure,database" \ --title "Production database connection details" \ -t mem --no-web # Procedure bkmr add \ "Deploy to staging: 1) Run 'make deploy-staging' 2) Wait for health check at /api/health 3) Verify logs in Grafana dashboard 'staging-deploys' 4) Run smoke tests with 'make test-smoke'" \ "procedure,deployment,staging" \ --title "Staging deployment procedure" \ -t mem --no-web # Preference bkmr add \ "User prefers pytest over unittest. Test files go in tests/ not __tests__/. Always use fixtures, never setUp/tearDown classes. Parametrize over duplicate test functions." \ "preference,testing,python" \ --title "Python testing conventions" \ -t mem --no-web # Episode bkmr add \ "2026-04-04: Debugged auth middleware timeout. Root cause: JWT expiry was set to 5 seconds (not 5 minutes) in config/auth.yml. The 's' suffix was interpreted as seconds, not minutes. Fix: changed '5s' to '5m'. See commit abc123." \ "episode,auth,debugging" \ --title "Auth middleware JWT expiry bug — 5s vs 5m" \ -t mem --no-web # Gotcha bkmr add \ "bkmr integration tests MUST run single-threaded (--test-threads=1) because they share a SQLite DB file. Parallel execution causes SQLITE_BUSY errors that look like test failures but are actually lock contention." \ "project:bkmr,gotcha,testing" \ --title "bkmr tests require single-threaded execution" \ -t mem --no-web Content Guidelines Since embeddings are built from content + title + tags, write memories that are search-friendly : Title : A specific, descriptive phrase — not "note" or "thing I learned" Content : Lead with the key fact. Add context after. Use concrete names, not pronouns. Tags : Include topic keywords beyond the classification (e.g., fact,database,postgres,production ) References over copies : Instead of pasting code, write "The retry logic in src/http/client.rs:45-60 uses exponential backoff with jitter. Max 3 retries, base delay 100ms." Deduplication (Critical) Before storing any memory, check if a similar one already exists: # Search for similar memories bkmr hsearch "your proposed memory content keywords" -t _mem_ --json --np -l 3 Decision logic: No match → create new memory Outdated match → update content with bkmr update --url "..." <id> Same content exists → skip, don't duplicate Related but adds info → update to merge both facts Update Examples Scenario 1: Outdated fact — port changed from 5432 to 5433 # Step 1: Search finds existing memory bkmr hsearch "production database" -t _mem_ -n fact --json --np -l 3 # Returns: id=42, url="Prod DB on port 5432", title="Production database config" # Step 2: Update the content (port changed) bkmr update --url "Production PostgreSQL 15 on port 5433. Pool max 50." 42 Scenario 2: Enriching a memory — adding new info to existing memory # Step 1: Search finds a thin memory bkmr hsearch "auth service" -t _mem_ --json --np -l 3 # Returns: id=87, url="Auth uses JWT with 24h expiry", title="Auth token config" # Step 2: Enrich with more detail bkmr update --url "Auth uses JWT with 24h expiry. Refresh tokens in Redis (not DB). Token rotation enabled. JWKS endpoint at /api/.well-known/jwks.json." 87 Scenario 3: Fixing a bad title — improving searchability bkmr update --title "Auth service: JWT expiry, refresh tokens, JWKS endpoint" 87 Scenario 4: Reclassifying a memory — was stored as fact, should be gotcha # Replace all tags (must include _mem_ and new classification) bkmr update 87 -t "_mem_,gotcha,auth,jwt" -f Scenario 5: Adding topic tags — make memory more discoverable # Additive: keep existing tags, add new ones bkmr update 87 -t redis,security 3. Decision Tree: Should I Store This? Did I learn something new? ├── No → Don't store └── Yes ├── Is it in the source code, docs, git history, or derivable by reading the codebase? │ ├── Yes → Don't store (code is source of truth; git log recovers changes) │ └── No │ ├── Is it trivial or obvious? │ │ ├── Yes → Don't store │ │ └── No │ │ ├── Would a future session benefit from knowing this? │ │ │ ├── No → Don't store │ │ │ └── Yes │ │ │ ├── Could I re-derive this by reading code + git log in < 5 min? │ │ │ │ ├── Yes → Don't store (re-derivation is cheaper than stale memory) │ │ │ │ └── No │ │ │ │ ├── Does a similar memory already exist? │ │ │ │ │ ├── Yes → Update existing (bkmr update --url "..." <id>) │ │ │ │ │ └── No → Create new memory │ │ │ │ └── Done │ │ │ └── Done │ │ └── Done │ └── Done └── Done 4. Anti-Patterns Anti-pattern Why it's bad Do this instead Putting content in -d instead of url Breaks embeddings AND memory display First positional arg = content Missing -t mem flag Memory has no _mem_ tag, invisible to queries Always use -t mem when adding Missing classification tag Unfilterable, breaks taxonomy Always include exactly one of: fact/procedure/preference/episode/gotcha Missing -t _mem_ on queries Searches entire DB, returns noise Every read query needs -t _mem_