Core concepts

The building blocks of Penumbra and how they fit together — one graph, a small set of primitives, and the composition that makes them powerful.

Penumbra is a small set of building blocks that compose. Every capability in the platform — extraction, memory, agent tools, verification — is these same blocks arranged differently, so once you know the blocks, every page in these docs reads as a variation on a theme you already understand.

Read this page as three lists: the nouns you work with, the verbs you call on them, and the rules that hold on every surface.

One graph

Everything lives in a single typed knowledge graph of entities and relationships. Planes partition it by role — interpreted knowledge, raw mirrors of external systems, agent memory, retired history — and every entity traces back to the source it came from. You never manage storage; you decide what the graph can hold and what lands in it.

The bricks

Primitive	What it is	Where it’s defined
Shape	Your domain model, made executable: entity types, their properties, the relationships between them. The central primitive — everything else is governed by it.	What is a shape
Type, property, relationship	The internals of a shape. Relationships are first-class and typed, not free-form edges.	Shapes & the graph
Entity & edge	Typed instances in the graph, conforming to a shape.	Explore & retrieve
Source	Registered raw material, and the provenance every entity traces back to.	Sources
Delta	A reviewable, revertible set of staged changes. Every write to the graph goes through one.	Deltas
Memory	A typed observation — what an agent or person learned, scoped to who should share it.	Memory
Project	The boundary: shapes attach to it, keys scope to it, agents operate inside it.	Projects & scopes

How they compose

The primitives are simple on their own. What they form together is the part worth understanding:

• One ontology. The shapes attached to a project define your entity types and the relationships allowed between them. Traversal follows those defined relationships, so an agent walks real edges instead of guessing.
• Context slices. Named, reusable subsets of the graph, compiled for a purpose — the unit of “give the agent exactly this context.”
• Governed writes. Shapes carry an adherence mode (strict or loose), every write stages through a delta, and access is scoped to a project. You do not opt into this per call; it is how the graph works.
• Versions and lineage. Shapes are versioned, deltas are revertible, and the graph records what produced what — semantic git for meaning.

The verbs

These are the operations you call. Each acts through a shape, not on the raw graph directly:

Verb	What it does	Surface
capture	Stage one typed entity.	pb.capture, penumbra_capture
extract	Coerce source material into many entities through a shape.	pb.extract
search / recall	Retrieve typed results across entities, sources, and memory.	pb.search, pb.memory.recall
traverse	Walk relationships along the grammar.	penumbra_traverse
synthesize	Turn recalled structure into a briefing that carries its own evidence.	pb.memory.synthesize
materialize	Publish a compiled shape draft into a project.	Materialize

Checking your work

Putting something in or pulling something out leaves one question open: is what I have good enough to act on? The decision-quality surface (pb.dq) answers it — check whether a subject is fit for a purpose, audit whether a staged change would degrade the graph, trace whether a briefing’s claims are backed by stored sources, repair what’s missing. The answer is a disposition plus findings, never a score.

One model, many schemas

A shape is not only for Penumbra. Define it once and use it both directions:

• Export it. The same shape becomes a provider-ready structured-output schema (OpenAI, Anthropic, Gemini, Firecrawl) via shape_workbench_export_schema, the tools your shape exposes to agents (see the Workbench), and the bundle that governs what an LLM may produce when extracting.
• Generate one. Go the other way: a website or document becomes a proposed shape, and a foreign API’s types can be mapped onto yours (IR, beta).

Define the model once; every surface that speaks schemas can consume it.

The invariants

Four rules hold everywhere, on every surface:

1. Every write stages through a delta. Capture, extract, memory — all of it. apply: false is your review gate; revert is your undo.
2. There are no confidence scores. Anywhere. Verdicts are dispositions and findings you can act on, not numbers you can’t.
3. Materialize is dry-run by default and requires a review_note. Nothing reaches a live project silently.
4. Starter shapes are discovered, not listed. pb.shapes.starters() returns the curated kit; list() returns only your project’s own shapes.

The loops

The guides each run one loop end to end, with a concrete success state:

Loop	Guide	You’ll know it worked when…
Remember → recall	Give your agent memory	it knows tomorrow what you told it today
Capture → search	Quickstart	your note became typed structure
Register → extract → apply	Cognitive ETL pipeline	a document became governed graph
Design → compile → materialize	The Workbench	your expertise became an executable shape
Trace → check → repair → act	Grounded copilot	the agent refused to act on thin context