Claude Context

claude-context

A ripgrep-backed search tool over ~/.claude (conversations, project memories, global memories, plans, agents). It resolves the real project path for a hit and scores/ranks results, so you don't have to open large files to figure out relevance.

Script: ~/.claude/tools/src/claude_context.py Invoke as: claude-context (assume it's on PATH; if not, run python3 ~/.claude/tools/src/claude_context.py ).

Core principle: two-phase search, not full-file reads

Never read a raw .jsonl conversation file or a whole memory directory to "look for" something — it burns enormous context for low signal. Instead:

1. Recall pass (cheap): search with --format json to get ranked

candidates (id, score, snippet, path, tags) — a few hundred tokens.

1. Expand pass (targeted): once you've identified the right hit,

--expand to pull the full section/content of just that one hit.

This mirrors how you'd want a human to work too: shortlist first, deep-dive only on the winner.

When to use which mode

| Situation | Command | |---|---| | "Have I dealt with X before, but I don't know where?" | claude-context "X" --recall --format json | | Know the exact phrase, want ranked hits | claude-context "X" --format json | | Found a promising hit, want full content | claude-context --expand --format json | | Remember the idea but not the wording | claude-context --related --format json | | Just want to browse what memories/plans exist | claude-context --list --kind memory --format json | | Want a quick sense of scale before committing | claude-context "X" --stats | | Need both terms present, not either | claude-context "X" -e "Y" --term-logic and --format json | | Only care about a time window | claude-context "X" --since 30d --format json | | Piping the real project path onward | claude-context "X" -l |

Output format

Always pass --format json (or jsonl/compact) when calling this tool yourself — the default rich output is for humans in a terminal and is wasteful/unparseable for you. Key fields per hit:

• id — short hash handle; pass to --expand/--related
• kind — conversation | project-memory | memory | agent-memory | plan | agent
• real_path — the actual filesystem project directory (for conversation/project-memory hits) — this is what the user means by "which project"
• score — relevance (frequency × kind-weight × recency × tag bonus); curated memory outranks raw conversation noise
• snippet, tags, date, tokens_est

Example workflow

User: "Did we already figure out a fix for websocket reconnect storms?"

claude-context "websocket reconnect" --recall --format json -n 10

→ parse JSON, pick highest-score hit (prefer kind: memory / project-memory over conversation).

claude-context --expand  --format json

→ read the full section/content, then answer the user with the actual prior solution and its source project (real_path).

If the top hits look thin or off-topic, broaden with:

claude-context --related  --format json

which re-searches using keywords extracted from that hit — useful when the original phrasing doesn't match what the user is asking now.

Other useful flags

-k/--kind — restrict to one or more of: conversation, project-memory, memory, agent-memory, plan, agent -i case-insensitive, -F literal string (not regex) -C N — N lines of context around a hit --tag — filter by frontmatter tag (memory/plan/agent files) --unique — collapse duplicate lessons copy-pasted across projects --budget N — cap total estimated output tokens (keeps top-scoring hits) --since/--before — 2026-07-01, or relative (3d, 12h, 2w) -o/--open — opens the best-matching path in $EDITOR (human use)

Do NOT

Do not use grep -r, find, or cat/Read on ~/.claude/projects/ or ~/.claude/memory/ directly — always go through this tool first.

Do not request --format rich for your own tool calls — it's decorative and costs more tokens to parse than it's worth.

Do not skip the recall pass and jump straight to --expand on a guess —always confirm the id via a search/recall call first.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: cs-shadowbq
• Source: cs-shadowbq/claude-context
• License: MIT

Install and usage instructions live in the source repository linked above.