Saving facts

There are four write paths into Sigil. Three of them you never invoke by hand.

Path	Who uses it	When
Claude Code hooks	Automatic	Every message you send, every tool that runs
sigil remember	You, or any agent with a shell	Explicit saves
MCP remember / ingest	MCP clients	When the agent decides something is worth keeping
Dashboard	You	Editing and correcting, more than creating

Automatic capture

In Claude Code, the Stop hook runs a classifier over your last message at the end of every turn. If it finds a preference, decision, constraint, or factual claim, it extracts atomic facts, links entities, and runs them through AUDM against existing memory.

PostToolUse separately captures observations from Edit, Write, and Bash, deduplicated by SHA-256 against a five-minute window so a loop of edits doesn’t produce fifty near-identical rows.

This is the path that matters. Everything below is for the cases it doesn’t cover.

sigil remember

sigil remember "Deploys go out Tuesday and Thursday, never Friday"

Remembered. (1 new)

The response tells you what actually happened — 1 new, 1 updated, 1 already known, or a combination. A save that reports already known is not a failure; it means AUDM found an existing fact above the skip threshold.

Multiple facts, one call

Each quoted argument is a separate fact:

sigil remember \
  "Postgres 15 in production" \
  "Redis is only used for rate limiting" \
  "The staging DB is read-only for agents"

One process, one daemon round trip. Prefer this over three commands.

From stdin

echo "The API gateway strips X-Forwarded-For" | sigil remember
pbpaste | sigil remember

Each non-empty line becomes a fact.

Options

Flag	Effect
--bg	Return immediately; the write completes in a detached process. Failures are recorded to the hook error log and surfaced by sigil doctor.
--namespace=<ns>	Write into a specific namespace instead of the configured default
--pod=<name>	Attach to a specific pod instead of the one derived from your working directory

--bg is for agents

A save runs a chain of LLM calls — classify, extract, AUDM decide. That’s seconds, not milliseconds. Inside an agent turn you don’t want to block on it:

sigil remember --bg "user prefers dark mode" "project uses Postgres LISTEN/NOTIFY"

Use the foreground form when you want to see the result, which is most of the time at a human terminal.

remember refuses documents

remember takes one short, self-contained statement. Hand it a markdown file, a spec, or a session transcript and it refuses — because shredding a document into fact rows loses the original irrecoverably. Use sigil ingest instead; it stores the whole thing and extracts facts. See Ingesting documents.

Where the fact lands

Sigil derives the target pod from your current working directory:

cd ~/work/payments-api
sigil remember "Webhook retries are idempotent on event_id"
# → attached to the payments-api project pod

Two cases need you to be explicit.

The fact is about a different project than the one you’re standing in:

sigil remember --pod=srver "F0 boots via direct kernel boot + virtio-blk"

Without the flag, a fact about srver typed inside another repo is filed under that repo, and you won’t find it when you go back to srver.

The fact is about you, not any project — a preference, a convention, how you like to work. Save it normally. Sigil keeps personal facts unscoped so they follow you everywhere. Don’t force those into a pod.

Sigil also files a fact into any project it clearly names, so mentioning the project inside the fact text usually does the right thing without a flag.

Namespaces

A namespace is a hard isolation boundary — separate teams, separate contexts, separate brains sharing one database.

sigil remember --namespace=engineering "We deploy with Argo, not Flux"
sigil search "deploy" --namespace=engineering
sigil namespace list

Most people never need more than the default. Pods are the softer, more useful tool for organizing memory within one namespace. See Pods and namespaces.

Importance and categories

You don’t set either — the extractor does.

Category comes from a fixed vocabulary of fourteen — four personal (preference, opinion, personal, experience) and ten knowledge (business_rule, workflow, architecture, convention, decision, domain_knowledge, key_insight, metric, issue, action_item). Filter by it:

sigil facts --category=decision --limit=30

Importance is vital or supplementary. Vital facts get surfaced globally through the vital pod kind — injected into every session regardless of what you’re asking about — and they survive lifecycle promotion even if nothing ever accesses them.

If something must always be in context, phrase it as a standing instruction rather than a topical fact. Sigil routes “how to work with me” statements to the directive kind, which reserves its own always-on slots precisely because query-driven recall can never surface them.

From MCP clients

MCP clients get two write tools:

remember(facts: string[], namespace?)   — save one or more atomic facts
ingest(content | path | url, ...)       — store a whole document

Unlike Claude Code there’s no hook layer, so the agent decides when to call them. A line in the client’s rules file makes that reliable — see Integrations for the exact wording per client.

Verifying a write

sigil facts --limit=10          # did it store?
sigil search "the topic"        # can it be found?
sigil status                    # totals across the KB

Storage and retrievability are different questions. A fact can be stored and still never rank high enough to be injected — Debugging retrieval covers that case.