Operations
FAQ
Getting started
Section titled “Getting started”Do I need Postgres?
Section titled “Do I need Postgres?”No. Choose Built-in at setup and Sigil runs PGlite in-process — Postgres compiled to WebAssembly, stored at ~/.sigil/db, zero install.
You need a real Postgres 13+ with pgvector only if you want multi-device memory, since the embedded database can’t be shared.
Do I need an API key?
Section titled “Do I need an API key?”No. Pick Claude Code as your LLM provider (it uses your existing subscription) and Ollama for embeddings, and you never enter a key. Ollama for both is fully local and free.
Why not npx sigil?
Section titled “Why not npx sigil?”Sigil is a background daemon plus editor hooks pinned to a path on disk. npx/pnpx run from a throwaway cache your package manager later deletes, which would silently break memory. Sigil detects an ephemeral install directory and refuses.
Windows?
Section titled “Windows?”WSL only. Native Windows is unsupported and refuses to install rather than half-working — the launcher shims and Claude Code hooks are POSIX shell scripts.
Compatibility
Section titled “Compatibility”Does it work with Cursor / Codex / Windsurf / Continue / Cline?
Section titled “Does it work with Cursor / Codex / Windsurf / Continue / Cline?”Yes. Anything that speaks MCP can use Sigil, and anything with a shell can use the CLI. See Integrations.
What you lose outside Claude Code is the hook layer — automatic injection and automatic capture. The agent calls the tools when it decides to. The memory engine is identical.
Can I use it with an agent that isn’t a coding assistant?
Section titled “Can I use it with an agent that isn’t a coding assistant?”Yes. If it can run sigil search or speak MCP, it works. See Custom agents, scripts & CI.
Does it replace CLAUDE.md?
Section titled “Does it replace CLAUDE.md?”No — they coexist. Keep CLAUDE.md for hard-coded project rules you maintain by hand. Sigil adds one @import line for its hot-context snapshot and handles everything searchable.
Privacy and data
Section titled “Privacy and data”Does my data leave my machine?
Section titled “Does my data leave my machine?”Only to the providers you chose. Memory storage is your own database. Embeddings with Ollama stay local. LLM calls — for extraction, AUDM decisions, classification, synthesis — go to whichever provider you picked.
Pick Ollama for both and nothing leaves. There is no Sigil cloud and no telemetry. The one outbound call Sigil makes on its own is the GitHub update check, which you can disable.
What if I paste a secret into a session?
Section titled “What if I paste a secret into a session?”Recognized secret patterns are masked at the ingest choke point — before classification, chunking, embedding, and extraction. Every downstream copy is masked, and read-side masking runs before injection too.
It’s pattern-based defence in depth, not a guarantee. Keep credentials in a secret manager.
Can I back up the brain?
Section titled “Can I back up the brain?”sigil export --format=json --output=backup.jsonpg_dump sigil > sigil.sqlExport carries facts, entities, and documents. pg_dump carries everything including embeddings and lifecycle state. See Backup and restore.
What does it cost to run?
Section titled “What does it cost to run?”Zero, if you use Ollama for both providers.
With hosted providers, cost lives almost entirely in ingest — one embedding call per chunk plus extraction calls per chunk. A 5,000-word document is on the order of twenty chunks.
Ongoing capture is cheap: one classification per message, extraction only when something memorable is found, AUDM only for ambiguous candidates. Search costs one embedding call.
How do I reduce it?
Section titled “How do I reduce it?”- Ollama for embeddings — that’s where the per-chunk volume is
- A cheap
llm.extractionModeland a smarterllm.decisionModel; see Providers ingest.eagerExtract = falseto store chunks without extracting facts- Don’t ingest source code or auto-generated files
How many tokens does it add to a prompt?
Section titled “How many tokens does it add to a prompt?”~1.5K for the query-driven injection, plus ~400–600 for the hot-context snapshot. That’s flat — it doesn’t grow with your corpus. That flatness is the main argument against putting everything in CLAUDE.md.
Behaviour
Section titled “Behaviour”Why didn’t it remember something I said?
Section titled “Why didn’t it remember something I said?”Four possibilities, and they have different fixes — Debugging retrieval walks each one. Start with:
sigil facts --limit=50 # was it stored?sigil why "your query" # how did it rank?Why did it forget something it knew?
Section titled “Why did it forget something it knew?”It probably didn’t. Facts aren’t deleted on a timer. What happens instead:
- A supersession — you said something that contradicted it, so the old fact stopped being retrieved
- Lifecycle: a low-importance fact nobody accessed never got promoted out of
fresh, so it never entered the ranking pool - A
claude_sessionfact hit its 90-day TTL — but its session summary was copied to the project pod, which doesn’t decay
See Memory decay.
Can I make sure something is always in context?
Section titled “Can I make sure something is always in context?”Phrase it as a standing instruction rather than a topical fact. “Keep explanations short” is classified as a preference and routed to the directive kind, which has reserved always-on hot-context slots.
Facts marked importance=vital also get six global slots.
What happens if a hook crashes?
Section titled “What happens if a hook crashes?”Your prompt goes through. Every hook wraps in a top-level try/catch that fails silently — the invariant is that a broken memory layer must never block a working prompt.
Errors append to ~/.sigil/.hook-errors.log. After five unacknowledged errors in 24 hours, sigil doctor exits non-zero so CI can catch it.
Teams and scale
Section titled “Teams and scale”Multi-user or team support?
Section titled “Multi-user or team support?”Single-user for now. Multiple installs sharing one Postgres works, and every write is attributed to its agent and device — but there are no per-user ACLs. Anyone with the connection string reads everything.
Device pairing is the closest thing: per-device roles (reader / writer / admin), namespace grants, and revocation.
How big can it get?
Section titled “How big can it get?”Retrieval is a single indexed SQL query over pgvector and tsvector — it scales the way Postgres does. Injection stays flat at ~1.5K tokens regardless of corpus size.
The published benchmark is small (n=100, ~25 chunks per question), so it says less about scale than it looks. Sigil’s architectural work — Hebbian edges, ACT-R activation, pod-aware blending — is designed to show at 10K+ chunks.
Can two people share a brain?
Section titled “Can two people share a brain?”Technically yes — point both installs at the same database. Writes stay attributed. But there’s no access control between them, so only do it with someone you’d give your database credentials to anyway.
Operations
Section titled “Operations”How do I uninstall?
Section titled “How do I uninstall?”sigil uninstall # unwire the agents, keep the datarm -rf ~/.sigil # remove everythingThen remove the export PATH line from your shell rc. See Uninstalling.
Memory stopped working after I upgraded Node.
Section titled “Memory stopped working after I upgraded Node.”sigil connectRe-pins the launcher shims and re-syncs every client’s config. This is the single most common failure.
Where can I see how retrieval actually works?
Section titled “Where can I see how retrieval actually works?”src/memory/search/hybrid.js is the entry point; src/memory/search/hybrid-sql.js is the single-SQL RRF and activation query. Pod kind contracts are in src/memory/pods/kinds/. Hooks are in src/hooks/.
Or read How it works first.