How it works

Sigil is three loops: capture, storage, recall. This page follows one sentence through all of them.

The shape

                    ┌──────────────────────────────────────┐
   Claude Code ───► │                                      │
   Cursor      ───► │        sigil daemon                  │
   Codex CLI   ───► │   (one process, per machine)         │ ───► your database
   Kiro        ───► │                                      │
   your script ───► │  hooks · MCP · CLI · HTTP · dashboard │
                    └──────────────────────────────────────┘

Every agent talks to one local daemon. The daemon holds the connection pool, the caches, and the peer endpoint, and it’s the only thing that touches the database. That’s why a search costs 33ms instead of a cold connect.

1 · Capture

You type, in Claude Code:

we’re dropping the Redis dependency — moving retries to the Postgres job table with SKIP LOCKED

Four hooks are wired into Claude Code, and two of them fire on this turn.

Hook	What runs
UserPromptSubmit	Before the model sees your message: hybrid search on it, top-K facts injected as additional context
PostToolUse	After each Edit / Write / Bash: capture observations, deduplicated by SHA-256 over a 5-minute window
Stop	At the end of the turn: classify your message, extract atomic facts, run AUDM against existing memory
SessionEnd	Summarize the session into its pod; promote facts that kept mattering

The Stop hook is the one that saves. It runs a classifier over your message; if it finds a preference, decision, constraint, or factual claim, it extracts atomic facts from it.

Agents without hooks — Cursor, Kiro, Codex CLI, anything MCP — call the remember and ingest tools instead, or shell out to sigil remember. Same daemon, same pipeline.

A broken memory layer must never block a working prompt

Every hook wraps in a top-level try/catch that fails silently. If Sigil is down, misconfigured, or mid-update, your prompt still goes through. Errors append to ~/.sigil/.hook-errors.log and sigil doctor surfaces them — after five unacknowledged errors in 24 hours it exits non-zero so CI can catch it.

2 · Storage

The sentence becomes an atomic fact:

content:     Retries run through the Postgres job table with SKIP LOCKED, not Redis
category:    decision
confidence:  high
importance:  supplementary
namespace:   default
visibility:  shared
pods:        project:payments-api, claude_session:2026-08-12

Before it’s written, two things happen.

Secret masking. Recognized secret patterns are masked at the single ingest choke point — before classification, chunking, embedding, and extraction. Every downstream copy is masked, so a credential never reaches your embedding provider.

AUDM. Add / Update / Delete / Merge. The new fact is compared against what you already know, and Sigil decides which of four things to do:

Decision	When
Add	Nothing similar exists
Update	A near-match exists and this refines it
Delete	This contradicts an existing fact, which is superseded rather than removed
Merge	Two facts are really one

That’s what stops a brain from becoming a pile after ten thousand saves. This turn triggers a supersession — the old “retries go through Redis” fact is marked superseded, with a link to its replacement. Deduplication has the thresholds.

Three storage layers sit underneath:

Chunks

~512-token blocks of ingested documents, each contextualized and embedded at 1024 dimensions. The raw material.

Facts

Atomic statements with category, confidence, importance, temporal validity, supersession links, and provenance back to a source.

Entity graph

Typed nodes — person, project, service, concept — connected by extracted relations, traversed with recursive CTEs.

Everything is attached to a pod: a typed container with declared retrieval behaviour. Session pods decay after 90 days; project pods never do.

3 · Recall

Thursday. You open Cursor in the same repo and ask about retry semantics.

Hybrid search runs as a single SQL query:

pgvector cosine similarity  ─┐
                             ├─► Reciprocal Rank Fusion (K=20) ─► candidate set
tsvector BM25 keyword match ─┘

Vector search finds “retry semantics” ≈ “webhook retries” even with no shared words. Keyword search catches exact identifiers — SKIP LOCKED, event_id — that embeddings blur. RRF fuses the two ranked lists without needing their scores to be on the same scale. Vector results carry weight 1.0, keyword 0.7.

Then two re-ranking passes:

• ACT-R activation — recency × frequency, from cognitive science. Bounded to a (1 + 0.10 × activation) multiplier so a frequently-used fact wins ties but can’t beat a materially better match.
• Hebbian co-retrieval — facts returned together before get stronger ties, and boost each other on later queries. The graph that emerges is “things you think about together”, built passively from real query behaviour.

Finally, results below the relevance floor are dropped, pod scope is applied, and visibility filters out anything scoped to a different agent or device.

Hybrid search and Ranking go deeper.

4 · Injection

Retrieved facts reach the model two ways.

Query-driven, per prompt. The UserPromptSubmit hook injects the top-K results for this prompt. Around 1.5K tokens, regardless of whether your corpus has ten facts or a hundred thousand.

Query-independent, always on. A top-20 snapshot lives in ~/.sigil/CLAUDE.md and is imported into your global Claude config. Zero latency, always present.

The second one exists because recall is query-driven, and that fails completely for standing instructions. “Keep explanations short” is relevant to every answer and semantically similar to almost no prompt — so it would never be retrieved. The hot-context snapshot is the channel that fixes it, and the directive kind reserves slots in it specifically for that class of fact.

The snapshot is a blend across active pod kinds, each with its own budget: 6 slots for the current session, 4 for the project, 4 for recently-active people, 3 for matching playbooks, 6 for globally-vital facts.

Why the daemon exists

A hook has to be fast. Cold-starting Node, connecting to Postgres, and running a search on every prompt is 200–400ms you’d feel.

The daemon keeps all of it warm: one connection pool, one embedding cache, one Iroh endpoint, one write queue. Hooks and CLI calls become a Unix socket round trip. It auto-starts on first use; you only touch it for explicit lifecycle control.

sigil daemon status
sigil daemon logs --follow
sigil daemon restart

See Architecture.

The invariant

A broken memory layer must never block a working prompt.

Everything above is designed around that. Hooks fail silently. Search has timeouts. The daemon circuit-breaks after repeated spawn failures rather than retrying forever. If Sigil breaks, you lose memory — not your work.

Next

Memory modelChunks, facts, entities, and how they relateHybrid searchThe retrieval query in detailArchitectureDaemon, transports, and process model