remindb Read Path

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.