Save facts a person tells you as entities

​

Outcome

Each fact is an entity or a relationship in the Graph, and it cites a note that holds the person’s words and the date. For each subject there is one entity. The person knows what, if anything, still waits for approval.

​

Before you start

• Orient first (recipe orient). A person’s own session applies a submit directly. A key or a connected agent waits for approval at the submit (card rule workspace.10).
• Ask the person for the date of what they told you. It is the note’s source date, and it is not today’s date unless they said so.
• Write down each fact in the person’s words before you go on.

​

Steps

1. Learn the types. Use only types the Shapes have.
   • CLI: penumbra shapes types. Expect each Shape with its entity types, each with its title field and description, then a relationships: list, such as Person —WORKS_AT→ Company.
   • MCP: grammar with the domain, or search_shapes (card shape).
   • A fact with no type to hold it needs a Shape change first (recipe change-a-shape).
2. Search for each subject before you create it. Penumbra does not compare an entity you stage by hand with the Graph (problem extraction-duplicates-existing-entity).
   • CLI: penumbra graph search "<name>" --type <Type>. If the answer warns lexical_coverage_none or lexical_coverage_partial, the search did not read the whole Graph. List the type instead with penumbra graph nodes --type <Type>.
   • MCP: omnisearch with the name, then read with entity:<id>.
   • If the subject exists, do not stage it again. Use it as an endpoint in step 5 (an existing entity’s name or id), or change it (card entity).
3. Save what the person said as a document, so every fact has a source to cite (card document, card rule passage.6).
   • CLI: penumbra files new /notes/<date>-<topic>.md --from <file.md> --source-date <date>.
   • MCP: create_markdown with the text, then update_file for the source date if the connection may set it (card rule file.5).
   • Expect created: /notes/<name>.md, a File ID and a version ID.
4. Read the version you will cite.
   • CLI: penumbra files versions /notes/<name>.md. Expect the version ID and content_digest sha256:… on the line of the current version.
   • To cite one passage, take its passage ID from the search result or from penumbra files chunks, and add it to the citation as chunk_id (card passage). chunk_id is optional, and the CLI needs no token for it.
   • MCP: read with the File reference returns a citation token for the version, or for exact words (card rule passage.3).
5. Open a workspace with a new name, and stage the facts with their citations (card rules workspace.1, workspace.2 and passage.2).
   • CLI: penumbra graph workspace open "<name>" --description "<what>", then penumbra graph workspace capture "<name>" <file.json>. The file lists entities and relationships. An endpoint is a ref from the same file, or the name or id of an entity that already exists.
     {
       "entities": [
         {
           "ref": "dana",
           "type": "Person",
           "name": "Dana Reyes",
           "properties": { "name": "Dana Reyes", "role": "Head of Operations" },
           "evidence": [
             {
               "file_id": "<file-id>",
               "version_id": "<version-id>",
               "content_digest": "<content_digest>",
               "chunk_id": "<passage-id>"
             }
           ]
         }
       ],
       "relationships": [
         {
           "type": "WORKS_AT",
           "from": "dana",
           "to": "Acme Corporation",
           "evidence": [
             {
               "file_id": "<file-id>",
               "version_id": "<version-id>",
               "content_digest": "<content_digest>"
             }
           ]
         }
       ]
     }
     
   • Expect staged N items into <name>, one line for each item with its handle, and a note that the Shape is pinned for this workspace.
   • MCP: capture in the full catalog and in Kits, with citation tokens.
   • Program: penumbra.workspaces.open({name}), then penumbra.domain.stage({workspace, entities, relationships}). A staged relationship takes a type, from and to; it sets no properties and no citations here.
6. Check the whole workspace, and compare the counts with the facts.
   • CLI: penumbra graph workspace validate "<name>". Expect valid: yes, would apply: 2 entities, 1 relationships, 0 updates, 0 deletions for the example above, and the submit command with its revision.
   • Validate warns about two staged entities with one name (duplicate_name). It does not warn that an entity with that name is already in the Graph.
7. Submit the revision you reviewed (recipe review-and-submit).
   • CLI: penumbra graph workspace submit "<name>" --revision <n> --request-id <key>.
   • Expect submission: applied, a counts line such as created 1 entity and 0 relationships, one line for each created entity with its ID, and exit code 0. Add --detail to list each relationship too. A key or a connected agent gets exit code 4 and outcome: pending; give the person the approval address and wait (problem change-waits-for-approval).

​

Check

• penumbra context entity <entity-id> shows the properties and a from: line that names the note, with its File and version IDs.
• penumbra graph nodes --type <Type> lists one entity for each subject you saved.
• penumbra graph counts shows the totals you expect.
• Nothing is saved until the submit says applied (card rule workspace.2).

​

If it goes wrong

​

Worth offering

• Offer to ask the person for facts you still lack, such as a role or a date, and to add them in a second workspace.
• If the person has documents that state the same facts, offer to extract from them (recipe extract-files). Extraction then adds citations to exact passages.
• Offer to relate the new entities to existing ones, such as a person to a company that the Graph already has.

​

Report

List each entity and relationship you saved, with its ID. Name the note that holds the person’s words, its date and its version. Say which subjects already existed and how you used them. Say what waits for approval and who decides. Say that you saved only what the person told you, and name any fact that no type could hold.

​

Keep going

Workspace · Entity · Relationship · Shape · Passage and citation · Document · Review a workspace and submit it · Extract entities from Files · Two entities have the same name · Two entities in the Graph are one thing · Approval