Everyday workflow

The honest answer is that most days you type nothing. This page is about the exceptions.

Monday — a new project

You point an agent at a repo Sigil has never seen. Seed it once:

cd ~/work/payments-api

sigil ingest ./README.md ./docs/ARCHITECTURE.md
sigil remember \
  "payments-api settles through Stripe; Razorpay is India-only and lives behind the same interface" \
  "Webhook retries are idempotent on event_id — never on payment_id"

Two minutes. From here, capture is automatic.

Sigil creates a project pod keyed on the git remote, so this knowledge is scoped to this repo — and follows it to any machine that clones the same remote, rather than being pinned to a path that only exists on your laptop.

Tuesday — you just work

Open Claude Code. Say things. The hooks do the rest:

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

At the end of that turn the Stop hook classifies the message, extracts an atomic fact, checks it against what you already know, notices it contradicts the stored “retries go through Redis” fact, and supersedes it. You did nothing.

Meanwhile PostToolUse is quietly capturing observations from the edits and commands that turn happened to run.

You'll see it acknowledged

A well-behaved agent will say something like “since you moved retries to the job table, I’ll…” on a later prompt. That’s the injected context being used. If it never happens, Debugging retrieval is the next stop.

Wednesday — a different agent

You open Cursor in the same repo and ask about retry semantics. Cursor has no hooks, so it calls the MCP search tool — and gets the same fact Claude Code wrote yesterday.

If your MCP client isn’t calling search on its own, that’s a prompting problem, not a memory problem. One line in its rules file fixes it; see Integrations.

Thursday — you need to check something

Three commands cover almost every question you’ll have:

sigil search "retry semantics"    # what do we know?
sigil why "retry semantics"       # why did those rank that way?
sigil facts --limit=20            # what went in recently?

sigil why is the one people underuse. It prints, per fact, the vector score, the keyword score, the fused RRF score, the pod it came from, its kind and importance — everything that decided the ordering.

Friday — correct something

Memory goes wrong in two ways, and they have different fixes.

A fact is wrong. Delete it:

sigil facts --limit=20
sigil forget 9fK2a1b0

A fact is right but leaking. An instruction you gave one assistant (“keep answers short”) shouldn’t put words in another’s mouth. A local path or port number is meaningless on your other machine. Scope it:

sigil visibility 9fK2a1b0 agent     # only the agent that wrote it
sigil visibility 4c81de77 device    # only this machine
sigil visibility 4c81de77 shared    # back to everything (the default)

See Provenance and visibility.

Any day — store a document

When someone hands you a spec, a postmortem, or a long transcript:

sigil ingest ./POSTMORTEM-2026-03-14.md
sigil ingest https://internal.wiki/runbooks/oncall --wait

Ingest keeps the full text and extracts facts from it. Later:

sigil docs                  # documents for this project
sigil docs doc-a1b2c3       # print one in full

Search finds the facts; docs gets you the source when the facts alone aren’t enough.

Monthly — maintenance

sigil maintain

Runs the periodic passes: promoting facts that have proven themselves out of fresh, closing editing windows, consolidating graph edges. Not required — nothing breaks without it — but it keeps the ranking pool clean. See Memory decay.

sigil status      # counts, by namespace and stage
sigil doctor      # is everything still wired?
sigil update      # pull the latest release

The shape of it

ContinuouslyHooks capture and inject. Nothing to run.

Per project, oncesigil ingest the docs, sigil remember the decisions that aren’t written down.

When something feels offsigil why, then forget or visibility.

Occasionallysigil maintain, sigil doctor, sigil update.

Using Sigil from inside an agent

Any agent with a shell can use Sigil with no integration at all. This is what the Claude Code instructions Sigil installs actually tell it to do:

sigil search "JWT auth setup"                          # before answering
sigil remember --bg "we use jose, not jsonwebtoken"    # when the user decides something
sigil ingest ./DESIGN.md                               # when the user says "save this doc"

--bg returns immediately and completes the write in the background — the right default inside an agent turn, where you don’t want to block on an LLM round trip. Batch multiple facts into one call:

sigil remember --bg "Prefers tabs" "Project uses Postgres 15" "Deadline is April 20"