Operations
Troubleshooting
Start here
Section titled “Start here”sigil doctor --deep--deep round-trips every connector — it actually spawns the MCP server and runs a hook, rather than checking that config files exist. That distinction resolves most reports.
If that doesn’t tell you enough:
sigil daemon logs --followOr open the dashboard’s Activity screen, which streams every hook fire, search, and LLM call live.
“Memory stopped working”
Section titled ““Memory stopped working””By far the most common report, and it has one common cause: a stale path after a Node version switch, a reinstall, or an update.
sigil connectRe-pins the launcher shims in ~/.sigil/bin/ and re-syncs every client’s generated config. Touches no database, no provider, no API key.
sigil connect --clients claude-code,cursor # or just somesigil connect --dry-run # see what would changeIf that doesn’t fix it, work down the list below.
The installer fails
Section titled “The installer fails”| Symptom | Cause |
|---|---|
Sigil does not support native Windows | Correct. Install inside WSL. |
| Node version error | Sigil needs Node 20+ |
git: command not found | Sigil installs as a git clone and updates by fast-forwarding it |
| Refuses to set up from a cache directory | You ran it via npx/pnpx. Use the installer or npm install -g. |
The dashboard won’t open
Section titled “The dashboard won’t open”sigil daemon statussigil daemon logssigil daemon url # the URL, with its auth tokenIf the daemon isn’t running, sigil daemon start --foreground shows you why in the terminal instead of a log file.
Port 7777 already taken? Change http.port in ~/.sigil/config.json and restart.
The database step fails
Section titled “The database step fails”| Message | Fix |
|---|---|
| Connection refused | Postgres isn’t running, or the host/port is wrong |
extension "vector" is not available | Install pgvector. The dashboard offers a one-click fix; the pgvector/pgvector Docker image has it preinstalled. |
| Authentication failed | Check user and password. Managed providers usually need ?sslmode=require. |
| Migrations fail on a pooled URL | Sigil routes migrations to the direct endpoint automatically. If you pasted a pooler host with no direct equivalent, use the direct one. |
Or sidestep it entirely: choose Built-in and get a zero-install PGlite database.
The provider test fails
Section titled “The provider test fails”| Provider | Common cause |
|---|---|
| OpenAI / OpenRouter / Voyage | Bad key, no credit, or a network egress block |
| Ollama | Not running (ollama serve), or the model isn’t pulled |
| Claude Code | The claude binary isn’t on the daemon’s PATH — set llm.cliPath |
| Codex | Same, llm.codexPath |
Under launchd or systemd the daemon gets a stripped PATH and can’t see ~/.local/bin or nvm directories. That’s what cliPath exists for.
Capture
Section titled “Capture”Facts aren’t being saved
Section titled “Facts aren’t being saved”sigil facts --limit=20 # is anything landing at all?sigil doctor # are the hooks registered?If hooks are registered and nothing is landing, check the dashboard’s Activity screen for the turn in question. You’ll see one of:
- The classifier skipped it. It’s deliberately conservative. Say it more declaratively, or run
sigil remember. - Extraction produced nothing. The message had no atomic assertion in it.
- AUDM said “already known”. Check for a near-duplicate with
sigil facts. - The hook errored.
~/.sigil/.hook-errors.loghas the detail.
Hook errors are accumulating
Section titled “Hook errors are accumulating”sigil doctor # reports the countcat ~/.sigil/.hook-errors.logsigil doctor --ack # acknowledge once you've read themAfter five unacknowledged errors in 24 hours, sigil doctor exits non-zero so CI can catch a degrading install.
Duplicates are piling up
Section titled “Duplicates are piling up”memory.skipThreshold (default 0.88) is too high for your LLM’s ability to recognize restatements. Lower it slightly in Settings → Advanced. This is the common adjustment on a local model. See Deduplication → Tuning.
Retrieval
Section titled “Retrieval”A fact exists but never comes back
Section titled “A fact exists but never comes back”sigil why "your query"Four causes, in order of likelihood — full walkthrough in Debugging retrieval:
- It’s too vague to rank on any query
- Your query shares no vocabulary with it
- It’s below
memory.minFactSimilarity(0.45) - It’s visibility-scoped to a different agent or device
It ranks in why but the agent doesn’t use it
Section titled “It ranks in why but the agent doesn’t use it”memory.injectionFloor (0.6) is higher than the search floor, deliberately — injecting weak matches into every prompt is worse than injecting nothing.
Or the agent isn’t calling search at all. For MCP clients that’s a prompting problem; see Integrations.
Search returns nothing at all
Section titled “Search returns nothing at all”An empty recall is sometimes infrastructure, not an empty brain:
sigil doctor # daemon up? database reachable? embedder working?sigil status # is there anything stored?Retrieval got worse over time
Section titled “Retrieval got worse over time”sigil maintain # promote, close editing windows, consolidate edgessigil facts --limit=100 # scan for duplicate pile-upIntegrations
Section titled “Integrations”An MCP client shows the server but errors
Section titled “An MCP client shows the server but errors”sigil connectsigil doctor --deepls -l ~/.sigil/bin/sigil-mcpAn MCP client doesn’t show the server
Section titled “An MCP client doesn’t show the server”Restart the client — most read their MCP config only at startup. Validate the JSON. Confirm you added the inner sigil object, not the whole {"mcpServers": …} wrapper, if your client’s format expects just the entry.
Tools are available but never called
Section titled “Tools are available but never called”Prompting, not plumbing. Each integration page has the exact wording for its client. The instruction that does the most work is “before answering questions about this project, call search”.
The HTTP transport returns 401
Section titled “The HTTP transport returns 401”The token rotated:
sigil register --http --printUpdate the Authorization header in your client config.
Performance
Section titled “Performance”Prompts feel slower
Section titled “Prompts feel slower”Cold hook invocation is 200–400ms, then warm. If that’s unacceptable, remove only the UserPromptSubmit entry from ~/.claude/settings.json — you keep asynchronous capture and the zero-latency hot-context snapshot, and lose per-prompt dynamic search.
Ingest is slow
Section titled “Ingest is slow”Expected — it’s the expensive operation. Check queue depth on the dashboard’s Engine screen and raise ingest.workerConcurrency if your machine has headroom (needs a restart).
On Ollama, ingest is much slower still. Consider a hosted model for llm.extractionModel only, keeping embeddings local.
The daemon is using a lot of memory
Section titled “The daemon is using a lot of memory”If the managed-session engine is on, lower poolSize or tokenBudget. Otherwise check llm.maxClaudeProcs (default 4) — that semaphore exists because an unbounded ingest fan-out once produced 1600+ live claude sessions.
I need to undo something
Section titled “I need to undo something”sigil facts --limit=50sigil forget <id> # wrong factsigil visibility <id> agent # right fact, wrong audiencesigil visibility <id> device # right fact, wrong machinesigil pod archive <uid> # a whole stale contextFor something that’s outdated rather than wrong: just state the current truth. AUDM supersedes the old fact and keeps the history.
I want to start over
Section titled “I want to start over”sigil export --format=json --output=backup.json # firstsigil reset --keep-db # config onlysigil reset # everythingStill stuck
Section titled “Still stuck”sigil doctor --deepsigil daemon logscat ~/.sigil/.hook-errors.logsigil statusThose four outputs describe almost any Sigil problem completely. Include them when you open an issue.