Your first memories

A brain is only as useful as what you put in it. This page is about the first fifty facts — the ones that decide whether Sigil feels like magic or like noise.

Facts and documents are different things

Sigil has two write paths, and using the wrong one is the most common early mistake.

	sigil remember	sigil ingest
Input	One short, self-contained statement	A file, a URL, a glob, a whole document
Stored as	A fact row, embedded and searchable	The full text plus facts extracted from it
Recoverable in full	No	Yes — sigil docs <uid>
Good for	“We use jose, not jsonwebtoken”	DESIGN.md, an RFC, a meeting transcript

remember refuses document-shaped input — anything with headings or multiple paragraphs. That guard exists because shredding a spec into fact rows destroys the original irrecoverably. If you want to keep a document, ingest it.

sigil remember "Deploys go out Tuesdays and Thursdays, never Friday"
sigil ingest ./RUNBOOK.md

What makes a good fact

Self-contained. A fact is retrieved months later with none of the conversation around it. It has to stand alone.

# no — meaningless out of context
sigil remember "we decided to use the second one"

# yes
sigil remember "Auth uses jose for JWT verification, not jsonwebtoken — jsonwebtoken's ESM story is broken"

Specific. Vague facts match every query weakly and win none of them.

# no
sigil remember "the API is complicated"

# yes
sigil remember "mycohort-api routes all payment writes through user_payment_registration_log; the Google Sales sheet is a mirror, not a source"

Durable. Store what will still be true next month. Today’s terminal output is not memory.

One idea each. Two facts in one row can only be retrieved together, and only superseded together.

sigil remember "Postgres 15 in production" "Redis is only used for rate limiting"

Each quoted argument is a separate fact. One command, one round trip.

Five categories worth seeding

Sigil classifies automatically, but these are the kinds of thing that pay off fastest:

Preferences”Named exports, never default exports.” · “Don’t use any without an escape-hatch comment.”

Decisions”We moved off Redis pubsub to Postgres LISTEN/NOTIFY in March — one less service to operate.”

Constraints”Staging DB is read-only for agents.” · “No new dependencies without approval.”

Architecture”The worker fleet reads from a single Postgres job table with SKIP LOCKED.”

Conventions”Migrations are timestamp-prefixed .cjs files under src/db/migrations/.”

The full vocabulary Sigil sorts facts into is in Memory model.

What not to store

• Secrets. Sigil masks recognized secret patterns at the ingest choke point, before embedding or storage — but don’t rely on that. Keep credentials in your secret manager.
• Anything the repo already says. Code structure, file layout, git history. Your agent can read those. Store the why, which the code doesn’t record.
• Conversation summaries. “We discussed the auth flow and agreed on a plan” is unretrievable. Store the conclusion instead.
• Transient state. Which branch you’re on, what’s currently failing. It’s stale in an hour.

Verify it landed

sigil facts --limit=10

9fK2a1b0 [architecture] We use Postgres LISTEN/NOTIFY for event delivery, not Redis pubsub
4c81de77 [preference] Named exports, never default exports

Then check it’s actually retrievable — storage and recall are different questions:

sigil search "how do we deliver events"

If a fact you know exists doesn’t come back, sigil why shows the ranking breakdown per fact — vector score, keyword score, fused RRF, pod, kind, importance:

sigil why "how do we deliver events"

That’s the debugging loop. Debugging retrieval covers what each number means.

Fix a bad memory

sigil forget 9fK2a1b0        # delete by id (the prefix from `sigil facts` is enough)

You rarely need to. When you state something that contradicts an existing fact, Sigil’s AUDM pass supersedes the old one automatically rather than storing both — Deduplication explains when it updates versus when it adds.

Where a fact goes

Every write is attached to a pod — a typed container. By default that’s the project pod for your current directory, so a fact you save in one repo surfaces there and doesn’t leak into unrelated work.

cd ~/work/mycohort-api
sigil remember "Payment sync compares UIDs to detect row mismatches"   # → mycohort-api's pod

sigil remember --pod=srver "F0 boots via direct kernel boot + virtio-blk"  # → a different project

Facts about you rather than any project — preferences, conventions, how you like to work — stay unscoped and follow you everywhere. Sigil sorts this out on its own most of the time; --pod is the override when it guesses wrong. See Pods.

Seed a project in one sitting

A useful ritual when you first point Sigil at an existing codebase:

cd ~/work/your-project

# 1. the documents that already explain it
sigil ingest ./README.md ./ARCHITECTURE.md ./DESIGN.md

# 2. the decisions that aren't written down anywhere
sigil remember \
  "Events go through Postgres LISTEN/NOTIFY, not Redis — we dropped Redis in March" \
  "Auth is jose, not jsonwebtoken" \
  "Deploys are Tuesday and Thursday only"

# 3. check what the brain now knows
sigil status
sigil search "architecture"

Then stop

After the seed, let capture happen on its own. In Claude Code the Stop hook saves what’s memorable from every message you send. Manually mirroring that is duplicated work — and AUDM will mostly just tell you it’s already known.

Next

• Everyday workflow — what using this actually looks like
• Saving facts — flags, batching, namespaces, background writes
• Ingesting documents — globs, URLs, and what the pipeline does to them