Provenance and visibility

A shared brain needs two things a single-user notes app doesn’t: a record of where every fact came from, and control over who gets to see it.

Provenance

Every fact carries its origin.

Field	What it records
Source document	The document and section it was extracted from, if any
Agent	Which agent wrote it — claude-code, mcp, cli, or a named custom agent
Device	Which machine
Namespace	Which partition
Created / accessed	When it was written, when it was last retrieved
Confidence	The extractor’s confidence: high, medium, low
Supersession	What replaced it, or what it replaced

Relations in the entity graph carry provenance too, so a graph edge can be traced back to the fact that produced it.

Why it matters

When something wrong is in memory, “which agent on which machine wrote this, and from what” is the question that resolves it in seconds instead of an afternoon.

sigil why "the topic"      # pods and scores per fact
sigil docs <uid>           # the source document, in full

The dashboard’s Knowledge Base detail panel shows the full chain, and Activity filters by agent — so you can see exactly what Claude Code wrote versus what came in over MCP.

Visibility

Some facts shouldn’t reach every agent or every machine. Three scopes:

Scope	Who can retrieve it
shared	Every device and every agent. The default for almost everything.
agent	Only the agent that wrote it
device	Only the machine that wrote it

sigil visibility <fact-id> agent
sigil visibility <fact-id> device
sigil visibility <fact-id> shared

The id is whatever sigil search or sigil facts printed — a prefix is enough. Changes take effect on the next read, on every device.

Agent scope

For instructions addressed to one assistant that would put words in another’s mouth.

“Call me sir.” “Always start your answers with a one-line summary.” “Use British spelling.”

These are directed at a specific assistant. Sigil’s extractor marks this kind of statement as vital — exactly the class of fact injected into every session regardless of pod. Unscoped, an instruction you gave one agent would silently reshape the voice of every other one.

Vital facts are visibility-checked too

The vital kind is declared “public”, but that’s a different question from visibility. The kind says the fact isn’t confined to a pod; fact.visibility says which agent it was addressed to. Vital facts are the path that most needs the check, and they get it.

Device scope

For facts that are true on exactly one machine.

“Postgres runs on port 5433 here because 5432 is taken.” “The dataset lives at /Volumes/scratch/corpus.” “This box has 128GB of RAM, so batch sizes can be large.”

Shared across devices, these make memory actively wrong. Sigil’s extractor scopes obvious cases automatically — local paths, ports, hardware. sigil visibility is the correction when it guesses wrong.

Namespaces are not access control

A namespace is a retrieval boundary. Anyone with the database connection string can read every namespace in that database.

Visibility scoping isn’t access control either — it’s addressing. It stops a fact reaching the wrong agent by accident; it doesn’t stop a determined reader.

For actual access control across machines, use device pairing, which issues per-device roles (reader / writer / admin) and namespace grants that can be revoked.

Write attribution and pod policy

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

In a shared-database setup this stops two machines racing on the same session pod, while leaving genuinely global facts writable from anywhere.

Secret masking

Recognized secret patterns are masked at the single ingest choke point — before classification, chunking, embedding, and fact extraction. Every downstream copy is masked, so a credential never reaches your embedding provider and never lands in the database.

The trade-off is that the classifier sees masked content. That’s accepted: for secret-bearing input the literal secret never improves routing, and preventing exfiltration outranks classifier fidelity. Masking is idempotent, so re-ingesting is safe.

Masking also runs on the read side, before injection, so a secret that predates the guard doesn’t leak into a prompt.

Defence in depth, not a vault

Pattern-based masking catches recognized shapes — API keys, tokens, connection strings with credentials. It is not a guarantee. Keep secrets in a secret manager and don’t paste them into an agent session.

Auditing what’s in there

sigil facts --limit=100
sigil facts --category=personal
sigil export --format=markdown | less

The dashboard’s Knowledge Base is faster for this — filter by namespace, category, or pod, and inspect any fact’s full provenance in the side panel.

Correcting memory

Problem	Fix
The fact is wrong	sigil forget <id>
The fact is right but reaching the wrong agent	sigil visibility <id> agent
The fact is machine-specific	sigil visibility <id> device
A whole context is stale	sigil pod archive <uid>
It’s outdated, not wrong	Say the new thing — AUDM supersedes the old one

The last row is the one people forget. You don’t usually need to delete anything; stating the current truth handles it, and keeps the history.