// Use ctxgrep for local semantic search, hybrid retrieval, and memory extraction across documents, notes, and project context. Triggers on: context retrieval, knowledge search, memory lookup, decision recall, document search, context packing, "what did we decide", "find relevant notes", "search project docs".
| name | ctxgrep |
| description | Use ctxgrep for local semantic search, hybrid retrieval, and memory extraction across documents, notes, and project context. Triggers on: context retrieval, knowledge search, memory lookup, decision recall, document search, context packing, "what did we decide", "find relevant notes", "search project docs". |
Use this skill when you need to search documents or notes, recall past decisions/preferences/constraints, assemble context bundles within token budgets, or search across a local knowledge base using exact, regex, semantic, or hybrid queries.
ctxgrep is a local-first CLI for searching documents, notes, memories, and project context. It is built for humans and AI agents to pull the right context into the current task without any external API.
Core capabilities:
curl -fsSL https://raw.githubusercontent.com/yetone/ctxgrep/main/install.sh | bash
Or from source:
cargo install --git https://github.com/yetone/ctxgrep
ctxgrep index <paths...> [options]
ctxgrep search <query> [PATH...] [options]
ctxgrep memory <query> [options]
ctxgrep pack <query> [options]
ctxgrep watch <paths...>
ctxgrep status
ctxgrep clear
ctxgrep doctor
Build or update the search index.
ctxgrep index <paths...> [options]
Options:
-r, --recursive: recursive scan--hidden: include hidden files--no-ignore: don't respect .gitignore--ext <exts>: file extensions to include (comma-separated)--max-file-size <size>: max file size (e.g. 5MB)--rebuild: rebuild index from scratch--with-memory: also extract memories during indexing--embedder <provider>: embedding provider (local, openai, none)--model <name>: embedding model nameBehavior:
--rebuild drops existing data and re-indexes everything.--with-memory runs the heuristic memory extractor during indexing.all-minilm-l6-v2, ~86MB ONNX) auto-downloads on first run.Search indexed documents.
ctxgrep search <query> [PATH...] [options]
Positional arguments:
PATH... (optional): one or more directories or files to search within. Defaults to the current working directory when omitted.Options:
--exact: literal text match--regex: regex pattern match--semantic: vector similarity search--hybrid: combines lexical + semantic + recency + importance (default)--top-k <n>: number of results to return (default 10)--json: output as JSON--full-section: show full section content--with-meta: include metadata in output--path <glob>: filter by path glob--tag <tag>: filter by tag--after <date>: filter results after date--before <date>: filter results before date--source <type>: filter by source type--budget <tokens>: token budget limit--global: search the entire index across all directories (disables the default CWD scope)Behavior:
grep, the search scope defaults to the current working directory. Only documents indexed under that directory are returned.PATH arguments to search across specific directories instead.--global to search the entire index regardless of where you are.--exact only when you know the precise phrase.--semantic for conceptual/meaning-based queries.--json for agent consumption.Search extracted memories (decisions, preferences, constraints, etc.).
ctxgrep memory <query> [options]
Options:
--type <TYPE>: filter by memory type (fact, decision, preference, definition, constraint, todo, summary)--json: output as JSON--top-k <n>: number of results (default 10)Behavior:
--type decision to find past architectural/design decisions before proposing changes.--type constraint to check for restrictions before making changes.Assemble a token-budgeted context bundle for a task.
ctxgrep pack <query> [options]
Options:
--budget <tokens>: token budget (default 4000)--json: output as JSON--include-memory: include memory objects--include-snippets: include text snippetsBehavior:
Watch paths for changes and update index automatically.
ctxgrep watch <paths...>
Show index status (number of documents, chunks, memories, etc.).
ctxgrep status
Clear all indexed data.
ctxgrep clear
Check environment and configuration.
ctxgrep doctor
Search results:
path — source file pathtitle — section titlesection_path — hierarchical section path (e.g. "Brand > Positioning")start_line / end_line — line rangescore — relevance score (0.0-1.0); below 0.3 is likely noiselexical_score / semantic_score — component scoressnippet — text contentwhy — match explanation array (e.g. ["title match", "semantic similarity"])Memory results:
type — memory type (fact, decision, preference, etc.)content — memory textsource — source file pathimportance — importance scoreConfig file: ~/.ctxgrep/config.toml
Key settings:
[embedding] provider: "local" (default), "openai", or "none"[retrieval] default_mode: "hybrid" (default)[retrieval] top_k: default number of results[memory] enabled: enable/disable memory extraction# 1. Check index state
ctxgrep status
# 2. Index if needed (only once per corpus)
ctxgrep index ~/project-docs --recursive --with-memory
# 3. Search for context in the current project directory (default CWD scope)
ctxgrep search --json "authentication design"
# 3b. Search the entire index when project scope is too narrow
ctxgrep search --json --global "authentication design"
# 4. Recall specific decisions
ctxgrep memory --json --type decision "authentication"
# 5. Pack context for a task with token budget
ctxgrep pack --json --budget 5000 "implement OAuth2 based on past decisions"
Broad knowledge search across entire index:
ctxgrep search --json --global "product positioning history"
Search scoped to the current project directory (default):
cd ~/my-project
ctxgrep search --json "product positioning history"
Search across specific directories:
ctxgrep search --json "product positioning history" ~/notes ~/docs
Recall decisions before making changes:
ctxgrep memory --json --type decision "database schema"
ctxgrep memory --json --type constraint "API versioning"
Prepare context for a coding task:
ctxgrep pack --json --budget 8000 "refactor auth middleware based on past discussions"
Search within a specific path glob:
ctxgrep search --json --path "docs/api/*" "rate limiting"
Full-text exact match:
ctxgrep search --json --exact "Lossless Feedback Loop"
Regex pattern search:
ctxgrep search --json --regex "TODO.*auth"
--json for structured, parseable output.--exact only when you know the precise phrase.pack for task preparation — it deduplicates, categorizes memories, and respects token budgets.score — discard anything below 0.3.memory --type decision to find past architectural/design decisions before proposing changes.--with-memory to enable memory extraction.ctxgrep doctor to diagnose issues with the environment or configuration.grep, search is scoped to the current working directory by default. Use explicit PATH arguments or --global to broaden the scope.