# Aim Query

> 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.

- Skill: `djalmajr/aim-query` (Agent Skill)
- Install (CLI): `npx skillmds@latest add djalmajr/aim-query`
- Raw SKILL.md: https://api.skillmd.com/api/skills/djalmajr/aim-query/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: djalmajr (https://skillmd.com/u/djalmajr)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/djalmajr/aim-query

---


# aim-query

Explicit recall from an ai-memory instance (complements the automatic session-start handoff).

## Steps

1. **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`.)
2. **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 (the reserved `default`/`_global` scope,
     under `_rules/`; ≥1.9 the server unions it into default-scoped queries as `global_scope_hits`), 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.
3. **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.
4. **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.