box-recall

name	box-recall
description	Find memories in a local box-memory workspace by ID, wikilink, slug, structured filters, or free text. Reads only from local _index.json files - no Box Search, no Metadata Query API, no network. Use when the user asks what do I know about X, what did we decide, find memories tagged Y, recall, or search my Box memory.
argument-hint	<query> [--kind=<kind>] [--tag=<tag>] [--team=<team>] [--limit=<n>]

/box-recall

If you see unfamiliar placeholders or need to check which tools are connected, see CONNECTORS.md.

Look up memories from the local Box Drive workspace. Multi-strategy ranking over local data only — no network calls.

Usage

/box-recall <query> [--kind=<k>] [--tag=<t>] [--team=<n>] [--limit=<n>]

Examples:

• /box-recall auth strategy — free-text
• /box-recall [[Login Flow]] — wikilink lookup
• /box-recall --kind=decision --tag=security — structured filter
• /box-recall --id=mem_01HXYZ... — exact fetch by memory ID

What to do

1. Read workspace config (_box-memory.json). If missing, surface "run /box-init first" and stop.
2. Verify backend is local (this plugin shouldn't be invoked on a backend: cloud workspace; if it is, surface a clear error pointing to the cloud variant).
3. Parse the query. Detect shape:
   • Memory ID (mem_...)
   • Wikilink ([[Title]])
   • Slug (kebab-case word)
   • Structured filter (kind:X tag:Y)
   • Free text
4. Determine target folders. Default: <workspace>/memories/ + every <workspace>/teams/<team>/memories/. With --team=<name>: just that team's folder.
5. Direct ID lookup. If query is a memory ID, walk each target folder's _index.json for by_id[<id>]. If found, read the file directly from local FS and return.
6. Wikilink / slug lookup. Same pattern, using by_wikilink[<title>] or by_slug[<slug>].
7. Structured filter. Use by_kind, by_tag, by_status inverted maps. Intersect across multiple filters.
8. Free-text match. For each entry in target folders' indexes, match query tokens against title, slug, tags (case-insensitive substring). Score: exact title=10, exact slug=8, exact tag=6, partial title=4, partial slug=3, partial tag=2.
9. Body content fallback (rare). If no matches from steps 5-8 AND total memories <50, read each memory's body and grep for query tokens. Slow but exhaustive. Warn the user before this kicks in.
10. Rank & return. Sort by score then updated_at desc. Default limit 10. For a "what did we decide about X" question (not a list query), return the best match's full content, not a list of snippets.

Result format

- id: mem_01HXYZ...
  title: <title>
  kind: <kind>
  status: <status>
  team: <team>
  tags: [<tags>]
  score: <n>
  matched_on: <title | slug | tag | wikilink | body>
  local_path: <relative path>
  updated_at: <ISO>
  excerpt: <first ~200 chars of body, with matched term highlighted>

Excluding superseded

By default, exclude status: superseded and status: archived. Include them when:

• --include-superseded flag
• User asks "history", "what was the previous decision", etc.
• Workspace setting include_superseded_in_recall: true

When showing superseded memories, follow the superseded_by chain and also surface the current version.

Stale-index detection

The index's updated_at should be ≥ every entry's updated_at. If you discover an entry whose updated_at is newer than the index's, the index is stale (someone wrote the file but the index wasn't refreshed). Surface a warning: "The index may be stale — run /box-index-rebuild to refresh." Still return results from the index for older entries.

Differences from cloud variant

• No Box Search — never available; if free-text body match is required across many memories, suggest /box-index-rebuild first, then re-run recall
• No Metadata Query API — Personal-tier-only behavior; structured queries use the local inverted maps
• No search_files_keyword fallback — local FS only
• Read latency is local FS — fast (sub-second) regardless of workspace size, vs Box API which depends on cloud latency
• file_id is null on entries — use local_path instead

Errors

• No workspace → run /box-init
• Permission denied reading a team folder → skip silently, continue with accessible folders
• Index file corrupt / unparseable JSON → surface clearly; suggest /box-index-rebuild

Don't

• Don't call any Box API. Don't read any URL.
• Don't return raw file contents when the user asked a specific question — synthesize the answer, cite the memory ID.
• Don't return superseded memories silently — always note when surfacing them.
• Don't fabricate matches. A wikilink target that doesn't resolve is a dangling reference; say so honestly.