recall

name	recall
type	command
description	Search the shared eidetic memory store and get back ranked, provenanced records. Drives `eidetic recall` with four search modes — exact (verbatim substring), approximate (vector/semantic), keyword (BM25 lexical), and hybrid (a weighted blend of vector+keyword, the default) — each hit carrying its text, full metadata, a relevance `score`, and a freshness `signal`. Recall passively reinforces matched records (bumps last_recall + recall_count). Shadowed and archived records are excluded by default; use --include-shadowed / --include-archived to retrieve them. The store uses visibility-aware routing: PUBLIC records inside a git repo go to <repo-root>/.eidetic/memory (committed, team-shared); PRIVATE records, or any record outside a git repo, go to $HOME/.eidetic/memory (never committed). An explicit EIDETIC_DATA_DIR wins and short-circuits to that single dir. Recall reads both stores and merges. The wrapper defaults queries to this agent's PERSONAL, PUBLIC scope (`--scope embodiment --visibility public`, suffix read from culture.yaml) — the memory scope+visibility convention (v1, docs/contract.md), matching where /remember writes — so a no-flag recall returns the full public pool, and Claude and the colleague backend recall each other's memories because both resolve the same suffix via this skill (pass --visibility private to also see this agent's own private records). Use when the user says "recall", "what do we know about X", "search memory", "have we seen X before", "look it up in memory", "eidetic recall", or before answering from scratch when prior context may already be stored. Pairs with the sibling /remember skill.

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 $HOME/.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)

Mode	What it matches	Needs embed server?
exact	case-insensitive verbatim substring (--case-sensitive to tighten)	no — offline-safe
approximate	vector cosine / semantic similarity	yes (falls back offline)
keyword	BM25 lexical; only records sharing a query term	no — offline-safe
hybrid	alpha*approximate + (1-alpha)*keyword (--alpha, default 0.5)	uses it when up

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:

Field	Notes
id	stable record identity
text	the stored chunk
type	record type
metadata	full provenance, round-tripped verbatim from ingest
score	relevance score from the chosen search mode (freshness-blended)
signal	freshness strength in [0, 1]; computed at recall time from age, recall frequency, and staleness
created	ISO-8601 ingest date (may be DATE_UNKNOWN for legacy records)
last_recall	ISO-8601 timestamp of the most recent recall hit (null if never recalled)
recall_count	number of times this record has been recalled (passive reinforcement counter)
lifecycle	active, shadowed, or archived
links	list of related-memory ids

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, PUBLIC scope (--scope embodiment --visibility public, suffix read from culture.yaml), matching where /remember writes and the memory scope+visibility convention (v1, docs/contract.md) — so a no-flag recall returns the full public pool. Pass --visibility private to instead query this agent's own private records plus the shared public pool (a private query still sees every public record; only a private record is scope-isolated). Pass --scope to query a different scope entirely; 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 lobes fleet gateway (http://localhost:8001/v1, model Qwen/Qwen3-Embedding-0.6B, reranker Qwen/Qwen3-Reranker-0.6B); override with EIDETIC_EMBED_URL / EIDETIC_EMBED_MODEL / EIDETIC_RERANK_MODEL. exact/keyword ignore it. The gateway fronts every role on that one port — the per-role vLLM containers are not published to the host, so a per-gear port is always wrong. Confirm the live value with lobes endpoint embedder.
• The gateway enforces a bearer token. eidetic reads it from EIDETIC_EMBED_API_KEY, else COLLEAGUE_API_KEY, else CULTURE_VLLM_API_KEY. With none set the request 401s and recall silently degrades to the offline lexical fallback — so approximate/hybrid still answer, but not semantically. If semantic recall looks oddly literal, check the key first.
• 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 $HOME/.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 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.