reflect:recall
Retrieve relevant prior learnings from the global knowledge base. Hybrid vector + graph search over 170+ indexed learnings, reranked by confidence, recency, and tag overlap. Use when starting work, debugging a recurring problem, or before implementing a feature that may have prior art.
Best use case
reflect:recall is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
Retrieve relevant prior learnings from the global knowledge base. Hybrid vector + graph search over 170+ indexed learnings, reranked by confidence, recency, and tag overlap. Use when starting work, debugging a recurring problem, or before implementing a feature that may have prior art.
Teams using reflect:recall should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/recall/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How reflect:recall Compares
| Feature / Agent | reflect:recall | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
Retrieve relevant prior learnings from the global knowledge base. Hybrid vector + graph search over 170+ indexed learnings, reranked by confidence, recency, and tag overlap. Use when starting work, debugging a recurring problem, or before implementing a feature that may have prior art.
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
SKILL.md Source
# /reflect:recall — Retrieve relevant prior learnings
Queries the global learnings KB (GraphRAG + vector) and surfaces the top-N
most relevant learnings for the current work, reranked by confidence, recency,
and tag overlap.
## When to use
- Starting work in a project or on a new branch — "what do we know about X"
- Debugging a recurring issue — "have we seen this error before"
- Before implementing a feature — "has this pattern been tried"
- When the user references past work ("like we did in Y")
**Also fires automatically** via the SessionStart hook (see
`hooks/session_start_recall.py`) with a 3-result cap, any confidence
(reranked by confidence/recency/tag-overlap). This skill is the
explicit, higher-limit path.
## Quick reference
| Invocation | Behavior |
|---|---|
| `/reflect:recall <query>` | Default — 10 results, any confidence, markdown out |
| `/reflect:recall <query> --limit 5 --confidence HIGH` | Tight filter |
| `/reflect:recall <query> --mode local` | Graph-neighborhood search (finds related concepts) |
| `/reflect:recall <query> --mode global` | Community-based (broad patterns) |
| `/reflect:recall <query> --format json` | Structured output for programmatic use |
| `/reflect:recall <query> --no-cache` | Skip cache, force fresh query |
## Workflow
1. **Build the query** — combine the user's question with project context:
current cwd, branch name, any relevant tags the user mentioned.
2. **Run recall** — invoke `{{HOME_TOOL_DIR}}/skills/recall/scripts/recall.py`:
```bash
uv run {{HOME_TOOL_DIR}}/skills/recall/scripts/recall.py "$QUERY" --limit 10 --format markdown
```
3. **Inspect results** — each result has `[lrn-id]`, key insight, and how-to-apply.
4. **Fetch full docs if needed** — for any interesting learning ID, the user can
run `reflect search <id>` or check the reflect repo's `documents/` dir
(`~/.claude/global-learnings/documents/` by default).
## Query construction tips
- Short, focused queries beat long sentences (the backend does vector similarity).
- Include proper nouns: project names, tool names, error snippets.
- Add tags explicitly with `--tags a,b,c` for reranking boost.
## Backend details
- **Retrieval**: wraps the `reflect search` CLI (from `reflect-kb`,
install via `uv tool install reflect-kb`) as a subprocess. Resolved via
`shutil.which("reflect")`; falls back to the legacy
`~/.learnings/cli/learnings` only if the canonical CLI is missing.
- **Ranking**: `confidence × recency × (1 + tag_overlap_bonus)`.
- Confidence: HIGH=1.0, MEDIUM=0.7, LOW=0.4
- Recency: exp(-days_ago / 90), half-life ~60 days
- Tag bonus: 0.1 × count(query_tags ∩ learning_tags)
- **Cache**: per-query SHA1 hash at `~/.reflect/recall_cache/`, 1h TTL.
- **Log**: every recall is appended to `~/.reflect/recall_log.jsonl` for
future helpfulness analysis (Phase 6 of the retrieval plan).
## Related
- `/reflect:ingest` — populate the KB
- `/reflect-status` — KB health, coverage, pending reviews
- SessionStart hook — auto-recall on project entry (see `hooks/settings-snippet.json`)Related Skills
reflect
Full conversation scan for self-improvement. Detects behavioral corrections and knowledge signals, classifies them, proposes agent updates and knowledge notes with entity sidecars for GraphRAG indexing. Correct once, never again.
reflect-status
Show reflection metrics, pending reviews, sidecar coverage, and GraphRAG health. Read-only views into the reflect system state. Can also approve/reject pending low-confidence items.
reflect:ingest
The global knowledge indexer. Harvests ALL memory sources across all tools (Claude, Codex, Copilot, Gemini) and all project types into the unified GraphRAG + QMD knowledge base. Archives originals, generates entity sidecars, and dual-indexes for future retrieval. This is THE command that makes the knowledge base comprehensive.
reflect:errors-ack
Triage and acknowledge entries in the reflect errors sink (~/.reflect/errors.json). Invoked from the statusline ⚠N badge when pipeline errors accumulate (drain poison, parser crashes, ingest failures, hook timeouts).
reflect:cost
Report reflect drain spend over a time window — tokens split by cached (cache_read), uncached writes (cache_creation), and io (input+output), with a $ estimate, grouped by day / outcome / model / transcript. Reads the drainer's cost log and surfaces outlier runs and cache-reuse health (the 41.5M-token failure mode = low cache reuse + high cache writes). Use to answer "what is reflection costing me" for the last day / week.
reflect:consolidate
Project-level memory consolidation. Merges orphaned worktree memory directories into a single .agents/MEMORY.md for the current project. Deduplicates, sections, and proposes cleanup of orphan dirs. Does NOT index into the global knowledge base — use reflect:ingest for that.
workflow
Guide through structured delivery workflow with plan, implement, validate phases
webapp-testing
Toolkit for interacting with and testing local web applications using Playwright. Supports verifying frontend functionality, debugging UI behavior, capturing browser screenshots, and viewing browser logs.
validate
Verify implementation against specifications
ui-ux-pro-max
UI/UX design intelligence. 67 styles, 96 palettes, 57 font pairings, 25 charts, 13 stacks (React, Next.js, Vue, Svelte, Astro, Nuxt, SwiftUI, React Native, Flutter, Tailwind, shadcn/ui, Jetpack Compose). Actions: plan, build, create, design, implement, review, fix, improve, optimize, enhance, refactor, check UI/UX code. Projects: website, landing page, dashboard, admin panel, e-commerce, SaaS, portfolio, blog, mobile app, .html, .tsx, .vue, .svelte. Elements: button, modal, navbar, sidebar, card, table, form, chart. Styles: glassmorphism, claymorphism, minimalism, brutalism, neumorphism, bento grid, dark mode, responsive, skeuomorphism, flat design. Topics: color palette, accessibility, animation, layout, typography, font pairing, spacing, hover, shadow, gradient.
tui-style-guide
TUI style guide for consistent terminal interface design
token-usage
Show Claude Code token usage across sessions — daily, weekly, per-project, and per-session breakdowns. Parses {{HOME_TOOL_DIR}}/projects/**/*.jsonl for consumption data. Use when the user asks about token usage, costs, how many tokens were used, session statistics, or wants a usage report.