> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pnbr.io/llms.txt
> Use this file to discover all available pages before exploring further.

# How Penumbra organizes knowledge

> Understand projects, Shapes, sources, records, workspaces, and memory before using the MCP tools.

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

| Term                        | What it means                                                                  |
| --------------------------- | ------------------------------------------------------------------------------ |
| **Project**                 | The boundary around a team's Shapes, sources, records, and access.             |
| **Shape**                   | The types, fields, and relationships used to organize one kind of knowledge.   |
| **Source**                  | Original material such as text, a document, or a web page.                     |
| **Entity and relationship** | A structured record and its typed connections to other records.                |
| **Workspace**               | A proposed group of additions or edits that can be checked before submission.  |
| **Memory**                  | A decision, preference, fact, lesson, or observation saved for later sessions. |

## 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.

<Card title="Save and retrieve your first source" icon="play" href="/getting-started/quickstart">
  See the project and source concepts in a short Runtime tutorial.
</Card>