Guides

Pods and namespaces

Two mechanisms, two different jobs. Getting them the wrong way round is the most common organizational mistake.

	Pods	Namespaces
Boundary	Soft — affects ranking and hot-context slots	Hard — separate stores, no crossover
Assigned	Automatically, from context	Explicitly, by flag or config
Use for	Per-project, per-session, per-person scoping	Separate teams, clients, or contexts
How many you need	Many; they create themselves	Usually exactly one

Start with one namespace and let pods do the work. Reach for a second namespace only when you genuinely want two brains that can’t see each other.

Pods

A pod is a typed container with declared retrieval behaviour. Six kinds ship built in:

Kind	One per	Decays	Hot-context slots
`claude_session`	Claude Code session	90 days	6
`project`	git remote, or directory	never	4
`person`	contact you mention	never	4 (rolling 24h)
`playbook`	runbook you author	never	3 (when the project matches)
`directive`	virtual — standing instructions	never	reserved
`vital`	virtual — facts marked vital	never	6 (global)

You don’t create session or project pods. They appear when a session starts or you work in a new repo.

sigil pod list
sigil pod list --type=person
sigil pod show <uid>
sigil kind list              # the registered kinds and their contracts
sigil kind show project

Project pods key on the git remote

This detail matters. A project pod is identified by its normalized git remote, falling back to the absolute path only for repos with no remote.

A path is only meaningful on the machine that holds it — your laptop’s /Users/you/work/api and a cloud agent’s /workspace/api are the same project. Keying on remote makes them one pod; keying on path would give you two that can never see each other.

Session pods

One per Claude Code session, opening on the first hook fire and closing on SessionEnd (or after six hours of inactivity). Facts here decay after 90 days — session context is genuinely ephemeral.

When a session ends, its summary attaches to both the session pod and the project pod. The session copy expires; the project copy is durable.

sigil session current
sigil session list --limit=10
sigil session show <uid>

Person pods

Created when you mention someone repeatedly. Backed by a canonical entity so deduplication churn doesn’t lose their metadata. Active on a rolling 24-hour window — people you’ve talked about recently occupy hot-context slots; people you haven’t, don’t.

sigil pod create --type=person --name="Priya Nair" \
  --github=priyan --role="Staff engineer, platform" \
  --relationship=peer

Explicit pod targeting

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

Use this when the fact is about a different project than the directory you’re standing in. Without it, the fact is filed under the wrong repo and you won’t find it later.

Playbooks

Procedural memory: how you do something, as opposed to what you know. A playbook pod holds the steps, checks, and gotchas for a recurring procedure — “how I debug a webhook signature failure”, “how we deploy on a Friday”.

Playbooks are always-active when the active project pod matches their project attribute, with three reserved hot-context slots. The deploy runbook for payments-api surfaces in payments-api sessions and is invisible elsewhere — which is the whole point.

sigil kind show playbook     # inspect the contract
sigil pod list --type=playbook

sigil pod create currently supports --type=person only. Until playbook creation lands, the practical substitute is to ingest the runbook as a document inside the repo it belongs to — it lands on that project’s pod and surfaces the same way:

cd ~/work/payments-api
sigil ingest ./RUNBOOK-deploy.md

Managing pods

sigil pod list --namespace=<ns> --limit=20
sigil pod show <uid>
sigil pod archive <uid>          # stop it being active; keep the facts
sigil pod delete <uid> --confirm # destructive

Archive is almost always what you want. Deleting a pod does not delete facts that also live elsewhere, but it does remove the membership that made them findable in context.

Namespaces

A namespace is a hard partition. Facts in one are invisible from another.

sigil namespace list
sigil remember --namespace=clientwork "Client X requires SOC2 evidence for every deploy"
sigil search "deploy" --namespace=clientwork
sigil search "deploy" --all-namespaces
sigil namespace delete clientwork --confirm

Two settings control the default behaviour:

Setting	Default	Meaning
`defaults.namespace`	`default`	Where this install writes. Always exactly one.
`defaults.searchNamespaces`	`[]`	Where this install reads. Empty means “just my own”.

The second exists for one specific case: two installs sharing a database under different namespaces that should still see each other’s memory. Set it to a list, or * for everything.

When to use which

A new repo. Nothing. The project pod creates itself.

Work for a client whose context must never mix with anything else. A namespace.

A fact that’s only relevant to one project. Nothing — it’s already scoped by the pod. Use --pod only if you’re saving it from a different directory.

A runbook that should surface automatically in one repo. A playbook pod.

An instruction to one specific assistant. Not a pod at all — visibility scoping.

Adding your own kind

Pods are pluggable. A new kind (slack_channel, github_pr, codex_session) is a contract file declaring identity, decay, hot-context budget, retrieval weights, and how to resolve its active scope. No schema migration — the hot-context blend iterates the registry, so a new kind slots in without touching the blend logic.

See Pod kinds for the contract fields.