Pods

A pod is a typed container for facts, and its type is a contract: it declares how facts inside it decay, how many hot-context slots the kind gets, how retrieval should weight recency against relevance, and how to work out whether the pod is active right now.

That’s the whole idea. Not a folder — a declaration of retrieval behaviour.

The six built-in kinds

Kind	One per	Decay	Hot slots	Active when
claude_session	Claude Code session	90 days	6	It’s the live session
project	git remote, or directory	never	4	You’re working in it
person	contact you mention	never	4	Mentioned in the last 24 hours
playbook	procedure you author	never	3	Its project matches the active one
directive	virtual	never	reserved	Always
vital	virtual	never	6	Always

sigil kind list
sigil kind show project
sigil pod list
sigil pod show <uid>

Why kinds rather than tags

A tag is inert; you’d have to write the retrieval logic that reads it. A kind carries its own behaviour, and the hot-context blend simply iterates registered kinds and asks each one for its facts.

That means a new kind — codex_session, slack_channel, github_pr — is a contract file, not a schema migration and not an edit to the blend logic.

{
  name: 'project',
  identityField: 'root_path',
  visibility: 'shared',
  activeMode: 'multi-active',
  hotContextBudget: 4,
  retrievalWeights: { recency: 0.6, relevance: 1.0 },
  importanceDefault: 3,
  ttlDays: null,
  writePolicy: 'origin-only',
  resolveActiveScope: async (ctx) => { /* which pods are live right now */ },
}

Full field reference in Pod kinds.

claude_session

One per Claude Code session, opened on the first hook fire and closed on SessionEnd — or after six hours of cursor inactivity. Exactly one is live at a time per install.

Facts here have a 90-day TTL. Session context is genuinely ephemeral: what you were debugging on a Tuesday in March is not something you want ranking against a query next year.

When a session ends, its summary attaches to both its session pod and the project pod. The session copy expires; the project copy is durable. That’s how a session’s conclusions outlive the session.

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

project

One per code project, and the most important kind in practice.

Identity is the normalized git remote, falling back to the absolute root path only for repos that have no remote. This is deliberate: 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 one project — keying on remote makes them one pod, keying on path would give two that could never see each other.

Multi-active: opening two different projects activates two project pods at once.

Facts never decay here. Architecture, conventions, and decisions accumulate across every session you ever run in that repo.

person

One per person you have a working relationship with. Identity is their primary platform handle — Slack user id, then GitHub username, then email — so partial-unique upserts on the dominant platform work.

Backed by a canonical person entity, so deduplication churn in the graph doesn’t lose their metadata.

Active on a rolling 24-hour window: people you’ve mentioned recently take hot-context slots; people you haven’t, don’t. Four slots, so recency matters.

sigil pod create --type=person --name="Priya Nair" \
  --github=priyan --email=priya@example.com \
  --role="Staff engineer, platform" --relationship=peer

playbook

Procedural memory — the CoALA framework’s term for it. How you do something rather than what you know about it. “How I debug a webhook signature failure.” “How we deploy on a Friday.”

A playbook is always-active when the active project pod matches its project attribute, with three reserved slots. The deploy runbook for payments-api surfaces in payments-api sessions and is invisible in every other repo.

Not yet creatable from the CLI

sigil pod create supports --type=person today. Until playbook creation lands, ingesting the runbook as a document inside the repo achieves most of the same effect — it attaches to that project’s pod.

vital — virtual

No row in the pod table. It’s a retrieval-time facet: facts marked importance=vital surface globally, six slots, independent of pod membership and independent of what you’re asking about.

Visibility scoping still applies — the kind being “public” means the fact isn’t confined to a pod, which is a different question from which agent it was addressed to. Without that check, “call me sir” told to one assistant would reach all of them.

directive — virtual

Standing instructions about how to work with you, always injected regardless of what the current prompt is about.

This kind exists because of a specific failure. Recall is query-driven: the hook searches with your literal prompt, so a fact only surfaces when it resembles what was just asked. That works for subject-matter facts and fails completely for standing instructions — “keep explanations short” is relevant to every answer and semantically similar to almost no prompt.

The symptom users report is an assistant repeatedly ignoring a preference they already stated.

The hot-context block is the query-independent channel that fixes it, but its always-on slots used to be owned by vital — and vital is pod-blind and effectively unfiltered, so in practice the six slots filled with whatever had been ingested most recently, from any project. Directives never got in.

So directives get their own reserved budget, taken before vital in the blend. A user-level instruction outranks project trivia for the scarcest space in the system.

Directives are selected by category: the personal categories minus experience (projects built and skills acquired are biography, not instruction), plus convention (naming rules and team standards are directives even though they’re filed as knowledge). workflow is deliberately excluded despite sounding directive — here it means process flows and state transitions, which would flood the slots with exactly the off-project noise the kind exists to displace.

The hot-context blend

Each active kind contributes up to its budget, in registration order, with content-level deduplication, capped at 20 facts total.

directive   reserved   ─┐
vital       6 slots     │
session     6 slots     ├─► dedup ─► top 20 ─► ~/.sigil/CLAUDE.md
project     4 slots     │
person      4 slots     │
playbook    3 slots    ─┘

Budgets are quotas, not guarantees — a kind with nothing to contribute yields its slots. See Hot context.

Pod scope in search

By default search spans everything. --scope narrows to the pods active for where you’re standing:

sigil search "retry" --scope
sigil why "retry" --pod-scope=global
sigil why "retry" --pod-scope=payments-api,platform

Write policy

Most kinds are origin-only: only the install that created the pod writes to it. vital is open.

This matters in a shared-database setup — it stops two machines racing on the same session pod, while leaving genuinely global facts writable from anywhere.

Managing pods

sigil pod list --type=person --namespace=<ns> --limit=20
sigil pod show <uid>
sigil pod archive <uid>            # deactivate, keep the facts
sigil pod delete <uid> --confirm   # destructive

Archive is almost always the right call. Deleting a pod removes the membership that made its facts findable in context, even where the facts themselves survive elsewhere.