How Penumbra organizes knowledge

Penumbra keeps the original material, the project’s interpretation of it, and proposed changes as separate objects. That separation lets agents work with shared knowledge without hiding where it came from or when it became live.

​

The six things you will encounter

​

A source is not a finding

Suppose an interviewee says, “Procurement adds six weeks to enterprise deals.” The transcript is the source. A project might interpret that statement as a finding about sales-cycle risk, connect it to an account segment, and leave an open question about sample size. Those records are useful because a Shape gives them consistent structure. They are still interpretations, so they should point back to the transcript. This is why evidence-heavy retrieval has two steps: read the relevant records, then quote the source passages that support them.

​

A workspace is not the live project

When an agent captures a finding or edits an account, it works in a workspace. You can read the proposed records, see how they relate, and run validation before submission. After submission, project policy decides whether the change is applied or waits for review. If a workspace fails validation, fix that workspace. Starting another one with the same content makes duplicates more likely and discards the useful error context.

​

Shapes and Runtime do different jobs

Runtime works with project knowledge: sources, records, searches, extractions, and workspaces. Shapes defines what those records can look like. Use the Runtime catalog first; many jobs can reuse an existing Shape. Open the Shapes MCP when no available Shape can express a concept or relationship the job needs. Publishing completes only when Runtime shows the new or updated Shape in the intended project.

​

Memory is supporting context

Memory carries decisions, preferences, and lessons between sessions. It can improve an agent’s judgment, but it does not replace source-backed project knowledge. When memory and current evidence disagree, show the disagreement and resolve the stale memory instead of silently choosing one.