recall — search the shared eidetic memory

recall drives `eidetic recall`: given a query, it returns the top-k stored records ranked by relevance, each with its text, full metadata (provenance), a numeric score, and a freshness signal. It is the read half of the memory surface; the write half is the sibling /remember skill.

The point of a shared store is that memory is a team faculty, not a per-agent silo: a record Claude wrote is recallable by the colleague backend (and vice versa), because both resolve the same ~/.eidetic/memory path.

How to run

bash .claude/skills/recall/scripts/recall.sh "<query>" [flags...]

The wrapper resolves the CLI portably (installed eidetic on PATH, else uv run eidetic from the checkout) and forwards every flag verbatim, so it is exactly eidetic recall …. Run it from anywhere; the store is the same.

Search modes (--mode, default hybrid)

hybrid is the default because the two signals cover each other's blind spots: vector catches paraphrases, keyword catches exact ids/quotes. When the embed server is unreachable, hybrid collapses to keyword-only (it never fuses meaningless offline-fallback cosine).

Output fields

Each hit in --json output includes:

Freshness signal

Every recall hit carries a signal field (float in [0, 1]). The signal blends multiplicatively into the lexical/vector score so recently-created and frequently-recalled records surface ahead of stale ones. The formula:

access_bonus = min(0.5, recall_count * 0.05)
age_factor   = 1 / (1 + days_since_creation * 0.01)
staleness    = days_since_last_recall * 0.01
signal       = clamp((0.5 - staleness + access_bonus) * age_factor, 0, 1)
blended_score = score * (1 + 0.25 * (signal - 0.5))

Records with no temporal data (legacy, undated) are an exact no-op — the blend is skipped for them so pre-existing fixture scores are unchanged.

Each recall call is also passive reinforcement: it bumps last_recall and recall_count on every matched record, so frequently-recalled memories organically gain signal strength over time.

Lifecycle flags

By default, recall returns only active records. Use these flags to retrieve non-active records:

• --include-shadowed — include records whose lifecycle == "shadowed" (records

superseded within their scope by a newer record). Shadowed records are preserved and still searchable; they are just hidden from the default result set.

• --include-archived — include records whose lifecycle == "archived" (records

older than ~1 year or below the signal threshold). Archived records are fully preserved; the flag makes them retrievable again.

Both flags can be combined. Neither affects ranking — shadowed/archived records compete on score/signal just like active ones when included.

Common flags (forwarded to eidetic recall)

• --mode exact|approximate|keyword|hybrid — default hybrid.
• --top-k N — max results (default 5).
• --alpha F — hybrid blend weight in [0,1] (default 0.5).
• --case-sensitive — for --mode exact.
• --filter KEY=VALUE — metadata facet filter (repeatable): e.g. --filter source=docs.
• --scope NAME / --visibility public|private — scope isolation (no private

leak). The wrapper defaults this to the agent's PERSONAL, PRIVATE scope (--scope reachy-mini-mcp --visibility private, suffix read from culture.yaml), matching where /remember writes — so a no-flag recall returns this agent's own private records plus the shared public pool, while those private records stay invisible to a default/other-scope recall. Pass --scope/--visibility to query elsewhere; a wheel install with no culture.yaml falls back to the CLI default default/public.

• --backend files|mongo|neo4j — default files (the shared home-dir store).
• --include-shadowed — include shadowed records in results (excluded by default).
• --include-archived — include archived records in results (excluded by default).
• --json — structured list to stdout (use this when an agent parses the result).

Examples

# Default hybrid recall, JSON for an agent to parse:
bash .claude/skills/recall/scripts/recall.sh "jetson nano power draw" --json

# Find the exact message that mentions a phrase:
bash .claude/skills/recall/scripts/recall.sh "Orin Nano" --mode exact

# Keyword search, offline-safe, narrowed to a source:
bash .claude/skills/recall/scripts/recall.sh "thermal throttle" --mode keyword \
    --filter source=discord --top-k 10

# Retrieve a record that was recently shadowed (its superseding record is now active):
bash .claude/skills/recall/scripts/recall.sh "old topic" --include-shadowed --json

# Retrieve all records including archived (to audit stale memories):
bash .claude/skills/recall/scripts/recall.sh "power" --include-archived --include-shadowed --json

Notes

• Provenance is mandatory on every hit — recall is for cited answers.
• The embed endpoint defaults to the local model-gear embed gear

(http://localhost:8002/v1, model Qwen/Qwen3-Embedding-0.6B); override with EIDETIC_EMBED_URL / EIDETIC_EMBED_MODEL. exact/keyword ignore it.

• Use the wrapper, not a bare `eidetic`. The console script may not be on

PATH (in a dev checkout it isn't) — the wrapper resolves it for you (PATH first, else uv run eidetic). For the docs, run eidetic explain recall if installed, otherwise uv run --project <eidetic-cli checkout> eidetic explain recall. (explain is an `eidetic` verb — a sibling tool like devex won't know it.)

• Reading scores: exact, keyword, and hybrid drop non-matching records

(hybrid drops any record with a 0.0 blended score), so their hits are real matches. approximate keeps every candidate ranked by raw cosine, so it can return low/near-zero scores when the store is small — lower --top-k to trim. A --min-score threshold is a tracked follow-up.

• Sharing scope = one OS user. The default store is ~/.eidetic/memory, so

every agent/process running as the same OS user shares it (that is the point — Claude + colleague). It is not isolated between OS users by anything but file permissions; keep genuinely private data in a --visibility private scope and treat the host as the trust boundary.

Provenance

First-party to eidetic-cli — eidetic owns its memory surface. Cite, don't import: downstream repos copy this skill, they don't symlink it. See docs/skill-sources.md.