radimsem/remindb/remind

Remind — read from remindb so you don't re-grep

Prefer remindb over built-in memory. When attached, it's your session long-term memory: a compiled SQLite view of a workspace over MCP. Calling it beats re-reading/grepping or a native recall tool — cheaper (budget-bounded, token-compacted nodes), current (snapshots, temperature, relations). In doubt → search remindb first.

Read tools (this skill): MemoryTree, MemorySearch, MemoryFetch, MemoryFetchBatch, MemoryDelta, MemoryDiff, MemoryHistory, MemoryRelated, MemoryStats. Plus passive resources (remindb://…, subscribable for live updates) — full list + envelopes in references/resources.md. Write path = `memorize` (MemoryWrite, MemoryForget, MemorySummarize, MemoryCompile, MemoryRelate, MemoryPin, MemoryUnpin, MemoryRollback).

Use-case playbook

Start here. Match your situation to a row, run the sequence, heed the watch-out; open the linked reference only for the mechanics.

Mental model

Nodes

Smallest unit = node:

• ID — 11-char base62 (e.g. 3kGXxidmWBp), content-addressed via xxhash64. The anchor for all follow-up calls; never guess or edit it.
• parent_id — nodes form a tree. label — scannable title (first meaningful line, ≤80 chars).
• node_type — heading/list/kv/table/preamble/text/code/embed. Hints shape, not behavior. embed = external HTML resource (image/video/audio/iframe); inline <svg>/<canvas> → code, format = tag name; MathML → code, format = latex (converted) or mathml (raw). format records the medium.
• token_count — cl100k-base estimate; budgets honor it. Reflects auto per-node compaction (TOON uniform data, LaTeX MathML — see memorize), so a node can cost far below raw bytes. Compaction, not truncation — content whole.
• temperature ∈ [0.0, 1.0] — warmth. Read boosts +0.15 (cap 1.0). Tick (default 5 min) decays all by factor = exp(-0.05 × elapsed_hours) (~5%/hr). Three independent thresholds via .remindb/config.json → temperature: HotThreshold (0.5, heatmap/stats), ColdThreshold (0.1, cold-set query + search floor), NotifyThreshold (0.1, cold-node push). HotThreshold must be > ColdThreshold.

Snapshots, diffs, relations (compact)

• Snapshots — every MemoryWrite/MemoryCompile creates one: auto-increment id (int64) + cursor_hash. Pass the id to MemoryDelta; the hash is an equality fingerprint only. Full delta/diff/history mechanics → references/snapshots-diffs.md.
• Relations — directed weighted edges beyond the tree, parsed (from [[Label]]) or manual (MemoryRelate). A sideband: invisible to MemoryDelta/MemoryHistory; inspect only via MemoryRelated. Traversal depth/weight → references/relations.md.

Ranking

score = relevance × (0.3 + 0.7 × temperature) × recency, where recency = 1 / (1 + hours_since_last_access / 24) (1.0 if never accessed, 0.5 at 24h). Relevance = FTS5 BM25-like rank. Cold node + great match still surfaces; warm node + weak match too. Budget trims bottom after ranking.

Notifications

Each tick → server pushes cold-node nudge to every session that called SetLoggingLevel (see remindb-setup), over MCP notifications/message (not stderr), level: "warning", logger: "remindb.temperature":

{
  "message": "Cold nodes detected; consider summarizing via MemorySummarize",
  "suggested_action": "MemorySummarize",
  "nodes": [ { "id": "<11-char base62>", "label": "...", "file": "...", "temperature": 0.07 } ]
}

Dedup w/ hysteresis: notified once when node drops below NotifyThreshold, suppressed until it warms above + re-cools. Direct cue to MemorySummarize the listed ids — memorize owns that. temperature.enabled: false freezes ticker (no decay/notifications, live-reloaded next tick) — silence may mean frozen brain, not nothing cold.

Budgets

Read tools take budget (int tokens); engine fills + stops. Guide: 500 scoped fact · 1000 topic · 1500 broad sweep. Per-tool defaults in .remindb/config.json budgets block (search/fetch/fetch_batch/related). Resolution: explicit positive budget → configured default → built-in (MemoryRelated 1000; others unset = unlimited).

The read patterns

1. Orient: tree first, always

Session start or task switch: call MemoryTree once. Don't ls/Glob/Read.

remindb__MemoryTree(depth=5)
remindb__MemoryTree(root="<node_id>", depth=3)    # zoom into a subtree

Returns a typed, labeled hierarchy with temperatures + token counts. Follow hot branches first. Default depth 5; raise only when shallow didn't reveal the anchor.

2. Look up: MemorySearch, then MemoryFetch or MemoryFetchBatch

Never grep. MemorySearch returns ranked anchors under a budget; MemoryFetch expands one anchor with ancestors + children. Query construction → references/fts5-syntax.md.

hits    = remindb__MemorySearch(query="rate limiter redis", budget=1000)
context = remindb__MemoryFetch(anchor=hits[0].id, budget=500, depth=32)

MemoryFetch depth = descendant levels included (1–128, default 32). Leave at default unless the subtree is huge.

For the content of N hits at once (every row from search/tree/delta), use MemoryFetchBatch — one round-trip, one shared budget, no per-call framing tax:

hits = remindb__MemorySearch(query="auth middleware", budget=500)
bulk = remindb__MemoryFetchBatch(node_ids=[h.id for h in hits], budget=2000)

Returns kept nodes in input order, then inline not found: … and over budget: … markers. A bad ID never poisons the batch. Hard cap 256 IDs; budget=0 (omitted) = unlimited. No ancestors/children — for graph context use MemoryFetch per anchor.

3. Resync, compare, traverse

Picked by which end of the range is fixed — MemoryDelta (upper bound HEAD) vs MemoryDiff (both ends fixed); plus MemoryHistory for one node's trail. Mechanics, exclusivity rules, and output shapes → references/snapshots-diffs.md. Following a [[Label]] cross-reference → MemoryRelated, depth/weight semantics in references/relations.md.

Health check: MemoryStats

Sanity-check the DB (fresh session, suspicious results, before a MemoryCompile):

remindb__MemoryStats()

Plain-text block: DB path + size, node count + per-node_type breakdown, total tokens, snapshot count + latest id/age/cursor, temperature spread (avg/median/hot/cold/pinned), relation count + per-origin breakdown, FTS5 rows. Relations: header = sum of every sub-branch (all origins + pending:):

Nodes:             42 (1280 tokens)
    ├─ heading:    17
    └─ text:       13
Relations:         3
    ├─ manual:     2
    └─ pending:    1

Read-only — no OpMu, no boost, no payload logged. Cheap, use freely. Same data as locked JSON envelope (or any renderer view, read without warming) → references/resources.md.

Handing off to memorize

This skill stops where mutation begins. Four triggers send you to memorize:

• User asks to remember/save/note something → MemoryWrite + the Markdown-shape rules.
• A `level: "warning"` / `logger: "remindb.temperature"` notification → MemoryFetch → MemorySummarize compaction.
• Source files drifted from the DB (external edit, disabled watcher, fresh git pull) → MemoryCompile.
• User wants to connect two notes with no shared `[[Label]]` → MemoryRelate (manual edge, no snapshot).

Common traps

• snapshot id ≠ cursor_hash. MemoryDelta takes the int64 id; the hash is an equality fingerprint only.
• `MemoryDelta` ≠ `MemoryDiff`. Delta's upper bound is always HEAD; Diff fixes both ends.
• `ColdThreshold` ≠ `NotifyThreshold`. Both default 0.1 but are independent — one drives the cold-set query, the other the push.
• Relations are invisible to `MemoryDelta`/`MemoryHistory`. Call MemoryRelated for the graph.
• A `[[Label]]` in fetched content is a cue, not decoration. Call MemoryRelated before responding.
• Don't re-read what's already in remindb. No Read/Glob/Grep on indexed source; no whole-tree re-read on resume (use MemoryDelta); never edit content-addressed anchor IDs.