Searching memory

Most retrieval is invisible: the Claude Code UserPromptSubmit hook searches on your behalf before the model reads your prompt. sigil search runs that same query engine by hand.

sigil search "how do we handle webhook retries"

Options

Flag	Effect
--limit=<n>	Max results (default 10)
--scope	Restrict to the active project and session pods. Default is to search everything.
--namespace=<ns>	One namespace, or several comma-separated
--all-namespaces	Search every namespace in the store
--graph / --no-graph	Expand results through the entity graph
--route	Let an LLM classify the query’s intent and adjust parameters
--synthesize	Return a written answer instead of a fact list
--chunks	Include raw chunk matches alongside facts

sigil search "deploy process" --namespace=engineering
sigil search "that decision" --scope          # only this project's memory
sigil search "auth" --limit=5 --graph

Scoping

By default, search spans everything Sigil knows. That’s usually right — the fact you need might have been captured in a different repo.

--scope narrows to the pods that are active for where you’re standing: this project, this session. Use it when a generic query is pulling in unrelated matches:

cd ~/work/payments-api
sigil search "retry" --scope

For finer control, --pod-scope takes auto, global, or explicit pod names — it’s available on sigil why, which is where you’ll usually want it.

Query routing

With --route, an LLM first classifies what you’re asking for and adjusts the search: whether to expand through the graph, whether to widen the result limit, whether to filter to particular categories, whether there’s a point-in-time constraint (“what did we decide before the migration”).

It costs an extra LLM call. The hook path uses it; interactive CLI search doesn’t by default.

Graph expansion

--graph takes the entities mentioned in your top results and pulls in facts connected to them, then re-ranks the merged set. It finds things a pure similarity search misses — you ask about “the payment flow” and get back a fact about a service that’s never named in your query but is one edge away.

Worth it for exploratory questions. Noise for precise ones.

Synthesis

sigil search "what's our stance on ORMs" --synthesize

Instead of a ranked list, an LLM reads the retrieved facts and chunks and writes an answer. Synthesis is on by default for the paths that need prose (search.synthesize in Configuration) and forces raw chunks into the retrieval set so the synthesizer has material to work from.

Turn it off when you want to see what’s actually stored rather than a paraphrase.

Entity search and the graph

Two more surfaces sit alongside fact search:

sigil search "Anmol"        # short, name-like queries auto-detect an entity

When a query is short and looks like a name, Sigil detects the entity first and searches from it — which produces much better results for “what do I know about X” than similarity alone. Over MCP this is explicit:

search_entity(name | type)      — find entities by name or type
traverse_graph(entity, depth)   — walk relations outward
get_entity_context(entity)      — relations, connected facts, graph position

From an agent

Any agent with a shell:

sigil search "JWT auth setup"

Any MCP client:

search(query, limit?, namespace?)

MCP clients should also call prime at the start of a session — it loads the hot-context snapshot the way Claude Code’s CLAUDE.md import does, so the agent starts warm instead of having to guess what to search for. See MCP tools.

When search returns nothing

sigil why "your query"

That prints the full ranking breakdown and is almost always faster than guessing. Debugging retrieval walks through reading it.

Empty results can mean a dead daemon

An empty recall is sometimes infrastructure, not an empty brain. sigil doctor distinguishes the two.