Skip to main content
This is Penumbra’s reflexive loop: an agent researches a domain into your graph as structured findings, then you design a shape informed by those findings, and operate on it. Default research → findings in the graph → a shape built from them → a shape in use.
Prerequisites: the Penumbra MCP connected to your agent and the Shapes Workbench connected. Both use your Penumbra account.

​
The preloaded Research shape

Every project ships with a system shape called Research that structures research findings. You do not design anything to start; the agent captures into it out of the box.
TypeCaptures
inquiryA line of investigation.
sourceWhere evidence comes from.
evidenceA specific observation drawn from a source.
findingA conclusion supported by evidence.
open_questionA gap still to resolve.
research_noteFreeform context.

​
The loop

1

Point the agent at a domain

In your agent (Claude Code, Cursor), ask it to research a domain and capture what it finds:
Research how expert litigation paralegals organize discovery. Capture your findings into Penumbra using the Research shape: inquiries, the sources you used, the evidence each surfaced, and the findings you reached.
The agent uses its own research tools to gather, and the Penumbra MCP to capture each finding as a typed entity, wired with the Research shape’s relationships.
2

Review what landed

The research is now structured graph data, not a document. Read it from the SDK, or ask the agent to summarize:
const findings = await pb.search("how paralegals organize discovery", {
  types: ["finding", "evidence"],
  include: ["entities"],
});
3

Design a shape from the findings

Open the Shapes Workbench and design a domain shape informed by what the research surfaced. The findings tell you which types, properties, and relationships matter, so the shape reflects how experts actually think about the domain, not a guess.
4

Materialize and use it

Materialize the new shape, then extract and capture against it. Your domain model is now grounded in real research that lives in the same graph it governs.

​
Why this matters

The research does not rot in a folder. It is queryable graph data the agent and you can reference while building the shape, and keep referencing after. The thing that taught you the domain stays in the system that operates it.

Connect an agent

Wire the Penumbra MCP into Claude Code or Cursor.

Design shapes

Turn the findings into a domain shape.