| name | aim-query |
| description | Manually recall durable knowledge from an ai-memory instance via the MCP (semantic/hybrid search, recent pages, prose catch-up). Use when the user asks to search the memory, 'have we done/decided X', 'what's the state of Y', or 'catch me up' — and you want an explicit recall rather than waiting for the auto-handoff. |
| metadata | {"short-description":"Manual recall from ai-memory"} |
aim-query
Explicit recall from an ai-memory instance (complements the automatic session-start handoff).
Steps
- Pick the instance. Read the configured ai-memory MCP server(s) from the repo's
.mcp.json / opencode.json / .codex/config.toml. If more than one is configured,
ask the user which endpoint to query. (Wired by aim-init.)
- Pick the scope. Default to the repo's
.ai-memory.toml workspace/project. The user may
widen it: a different project, a partial scope, or multi-scopes for cross-project recall.
scopes carries { workspace, project } per entry, so recall can span other workspaces
too (e.g. a shared rules project); global: true searches every project at once.
- Shared / global rules live in a dedicated scope (commonly
default/development,
under _rules/), separate from the repo's own project. ai-memory's auto-recall is
per-(workspace, project) and will not surface them — pull them explicitly:
memory_read_page with that workspace/project/path, or memory_query with
scopes:[{ workspace, project }]. Do this when the task needs the agent's standing
conventions (code-style, testing gates, workflow), not just repo-local knowledge.
- Choose the tool for the question:
memory_query — targeted semantic recall ("have we decided X", before proposing design).memory_recent — "what's been going on lately" (N most-recent pages).memory_explore — open-ended "catch me up" (prose digest; takes an optional focus).memory_briefing / memory_status — structured snapshot / lifetime counts.
- Report the hits with their
path + a one-line relevance note; offer to open a page
(read its markdown via the MCP or /api/v1/.../pages/<path>).
Keep queries specific. If recall returns nothing, widen the scope or rephrase before
concluding the knowledge isn't there.
