sysid/bkmr/bkmr-memory

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:

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

1. You may use topic tags for additional classification (e.g., database, postgres, deployment, auth).
2. To limit scope to a project, you may use a project tag. MANDATORY STRUCTURE for project tag: project:foo.
3. 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:

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.

hsearch matches every term literally — c++, node.js, foo-bar need no quoting. FTS5 syntax (phrases, AND/OR/NOT, prefix*) only works in search.

# 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

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:

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"