scottrbk Recalling knowledge from Forgetful
Retrieval quality is decided by how the query is shaped and scoped, and by treating coverage as something to judge rather than assume. Recall before proposing; history usually exists.
Invoking operations
Operations are named by registry name (query_memory, get_recent_memories, ...). Invoke
via whichever surface this agent has:
- MCP:
execute_forgetful_tool(tool_name="query_memory", arguments={...}) - CLI:
forgetful call query_memory --args '{"query": "..."}' --json
Get any operation's schema at runtime: how_to_use_forgetful_tool (MCP) or
forgetful tools info <operation> (CLI) — schemas are deliberately not repeated here.
Step 1 — Shape the query
query_context is a required parameter alongside query, not optional flavor text — the
call errors without it. Pass it deliberately: the two are embedded together, and ranking
genuinely shifts with intent ("auth" while implementing a feature ranks differently than
"auth" while debugging login). Include exact identifiers verbatim — error codes, function
names, config keys — the sparse full-text leg of the search matches them literally.
Done when: both query and query_context are written, not just a bare keyword.
Step 2 — Scope deliberately
Reads are cross-project by default, and usually should stay that way — knowledge transfers.
Narrow with project_ids when the task is project-bound; add strict_project_filter=True
to also keep linked memories inside those projects (the default False lets links cross
them). Use importance_threshold to cut noise — it excludes anything scored below the value
given, pairing naturally with forgetful-remember's rubric, where 5 is the noise floor for
bulk/automated captures. Adjust k to trade breadth for focus. These are filters layered on
top of semantic search, which stays the primary retrieval mechanism throughout.
Done when: the scope is a choice, not a default accident.
Step 3 — Judge coverage
Results are budgeted (about 8000 tokens / 20 memories), so assess coverage rather than non-emptiness:
truncated: true→ narrow the query (raise the threshold, scope the project) instead of accepting silent loss.- A miss on the first angle → re-query from a different facet (the feature area, the technology, the error text) before concluding the knowledge doesn't exist.
Done when: results are judged sufficient, or absence is confirmed from more than one angle.
Step 4 — Expand or escalate
Promising hits get get_memory for full content and links. When hits arrive as fragments,
reference entities, or trail across domains, the flat list is the wrong shape — switch to
forgetful-explore and walk the graph instead.
Done when: enough context is in hand, or the exploration skill has taken over.
Step 5 — Report
This skill is the single source of truth for the retrieval reporting convention:
- Found context: "Found N memories about X" with the load-bearing ones named.
- Nothing relevant: say so explicitly — "No existing memories about X."
- Off-target results: flag them — "Retrieved some context but it seems tangential."
A clean miss is also a signal: note the gap as a forgetful-remember candidate once the
task resolves it.
Done when: the user knows what memory contributed, even when the answer is "nothing".
Session-start catch-up
Re-entering a project after time away: get_recent_memories scoped to that project's ID is
the catch-up move — recent decisions and milestones without guessing queries. Run it as a
deliberate step, then continue into normal recall as the task demands.