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.