Skip to main content
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.

​
The map

  BOUNDARY        compile out: provider schemas · agent tool surfaces
                  map in:      shape proposals · IR mappings (beta)
                       ▲   one model, projected in both directions
  VERIFICATION    dq: check · gaps · audit · trace · repair
                       ▲   every forward verb gets a backward verdict
  OPERATIONS      capture · extract · search · traverse · synthesize · materialize
                       ▲   verbs act on composed structure, never raw graph
  COMPOSITION     ontology & grammar · context slices · adherence · versions
                       ▲   primitives compose under governance
  PRIMITIVES      shape · type · relationship · source · entity · delta · memory
                       ▲   instantiated on
  SUBSTRATE       one knowledge graph · planes · provenance
Read it bottom-up: each layer only depends on the layers below it. The sections that follow walk the same ladder.

​
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

PrimitiveWhat it isWhere it’s defined
ShapeYour 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, relationshipThe internals of a shape. Relationships are first-class and typed, not free-form edges.Shapes & the graph
Entity & edgeTyped instances in the graph, conforming to a shape.Explore & retrieve
SourceRegistered raw material and the provenance anchor every entity traces back to.Sources
DeltaA reviewable, revertible set of staged changes. Every write to the graph goes through one.Deltas
MemoryA typed observation — what an agent or person learned, scoped to who should share it.Memory
ProjectThe boundary: shapes attach to it, keys scope to it, agents operate inside it.Projects & scopes

​
Composition

This is where the leverage is. Primitives are simple; what they form together is not:
  • Ontology and grammar. The shapes attached to a project compose into one ontology with relationship rules across shapes. Traversal follows this grammar, which is why agent walks land on defined edges instead of crawling blindly.
  • Context slices. Named, reusable subsets of the graph compiled for a purpose — the unit of “give the agent exactly this context.”
  • Adherence and governance. Shapes carry an adherence mode (strict or loose); writes stage through deltas; access is project- and scope-bound. Governance is composed into the structure, not bolted on per call.
  • Versions and lineage. Shapes are versioned, deltas are revertible, and the graph records what produced what — semantic git for meaning.

​
The verbs

Operations act on composed structure, never on the raw graph:
VerbWhat it doesSurface
captureStage one typed entity.pb.capture, penumbra_capture
extractCoerce source material into many entities through a shape.pb.extract
search / recallRetrieve typed results across entities, sources, and memory.pb.search, pb.memory.recall
traverseWalk relationships along the grammar.penumbra_traverse
synthesizeTurn recalled structure into a briefing that carries its own evidence.pb.memory.synthesize
materializePublish a compiled shape draft into a project.Materialize

​
The backward pass

Every forward verb has a backward question: was that enough, and can I trust it? The decision-quality surface (pb.dq) answers it — check whether a subject is fit for a purpose, audit whether a delta would degrade the graph, trace whether a briefing’s claims are backed by stored sources, repair what’s missing. Verdicts are dispositions and findings, never scores.

​
The boundary

A shape is one model projected in both directions across Penumbra’s edge:
  • Compile out. The same shape becomes a provider-ready structured-output schema (OpenAI, Anthropic, Gemini, Firecrawl) via shape_workbench_export_schema, the agent tool surface you previewed in the Workbench, and the extraction bundle that governs what an LLM may produce.
  • Map in. Foreign material becomes structure: a website or document becomes a proposed shape, and a foreign API’s type system can be mapped onto your ontology through adjudicated correspondences (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:
LoopGuideYou’ll know it worked when…
Remember → recallGive your agent memoryit knows tomorrow what you told it today
Capture → searchQuickstartyour note became typed structure
Register → extract → applyCognitive ETL pipelinea document became governed graph
Design → compile → materializeThe Workbenchyour expertise became an executable shape
Trace → check → repair → actGrounded copilotthe agent refused to act on thin context