Teaching the agent what the file means

What you will take away from this lesson

After 502 the supplier’s price sheet is a table. Any agent on the scratch connection can select from it. What none of them knows is what a row means: whether unit_cost is landed or ex-works, whether it is per unit or per case, which warehouse column sku matches, and whether a SKU that is missing from the sheet means the supplier does not carry it or quoted zero.

You know all of that, because you opened the email. This lesson is the five minutes that move it out of your head: one message to the agent, one capture, one promotion, and one cited query. After that the file is not only queryable but understood, by your agent and by everyone else’s.

Learning Objectives

01Write a description that makes the file findable by the question somebody will ask, not by its filename.
02Capture the facts a header row does not carry: units, grain, effective dating, what the cost includes, which warehouse key the file joins on, and what a missing row means.
03Know which captures are live for you at once and which enter review before the whole team inherits them.
04Promote the captured facts to a knowledge page so every teammate’s agent recalls them without being told again.
05Record the first successful join as a reusable query by citing its call.
06Separate the two halves: registering publishes the data to everyone on the connection; the description and the knowledge page publish the meaning.

Where this lesson sits

This is the third lesson of the 500 series. The file is uploaded and registered; the table exists. This lesson is about the meaning, which no header row carries, and about who ends up holding it.

500 Series: Spreadsheets as Tables

Open index

The 500 series assumes the asset mechanics from the 300 series and the knowledge loop from 206. It ends where the 600 series begins: the point at which a monthly file needs more than a join.

What the header does not say

Registration reads the header row and turns each name into a column. That is all it can know. The supplier’s sheet has seven columns, and for every one of them the name is less than half of what an analyst needs before joining it to the warehouse. The ledger below is the running example: the header on the left, the facts the agent has to be told on the right.

The description you wrote at upload time in 502 covers the file as a whole. This is the column-level layer beneath it, and it is where confident, wrong joins come from when it is missing.

Seven columns: what the header says, and what the agent needs to know

Column	The header says	What the agent needs to know
sku	A product code.	Matches warehouse.public.products.sku exactly (SKU-000001), so the join needs no cast.
supplier_name	A name.	Always Blue Harbor Wholesale on this sheet. One sheet, one supplier.
unit_cost	A number.	The supplier’s landed cost per unit in USD from effective_date. Every registered column is text, so it is cast to DECIMAL(10,2) before arithmetic.
currency	A code.	USD so far. If a future sheet quotes in another currency, the cost is not comparable.
moq	An integer.	Minimum order quantity, in units, not cases.
effective_date	A date.	The first day the quoted cost applies, written YYYY-MM-DD.
lead_time_days	An integer.	Days from order to delivery.

Three facts are not in any column at all. A SKU absent from the sheet is one the supplier does not carry, not a zero, so the join has to be a LEFT JOIN with the null read as “not quoted”. The comparison the sheet exists for is unit_cost against products.cost, the cost of record, and against products.price for the projected margin. And a new sheet arrives every month and replaces this file.

Telling the agent in one message

There is no form for this. You tell the agent what the file means the way you would tell a new analyst, in one message, and the agent records it. The capture tool it uses is the same one it reaches for whenever it learns something worth keeping, and the reply says exactly what happened to the fact.

One message, one capture

You

A few things about that price sheet you should keep. Blue Harbor sends it once a month and the new one replaces the file. sku matches products.sku exactly. unit_cost is their landed cost per unit in USD from effective_date; compare it to products.cost for the change and to products.price for margin. moq is units. A SKU that is not on the sheet is one they do not carry, not a zero.

Agent

Recorded as business knowledge, with the query that just answered the category comparison cited as its source. The platform’s reply: “Captured. It will be reviewed before promotion to a shared catalog.” It is live for me now, and it is in the review queue for the team.

The call underneath was memory_capture with type business_knowledge, confidence high, and the category comparison’s call reference in sources. The reply has two halves on purpose: the memory is yours immediately, and the same text is now an insight waiting for review.

Personal memory and reviewed insight

One capture serves two audiences. It is live for you the moment it is recorded, and because it was captured as business knowledge it also enters the review queue, where a reviewer decides whether the whole team should inherit it. The two speeds are deliberate: your own agent should not have to wait for a review to use what you just said, and the organization should not inherit a claim nobody checked.

The same capture reaches two audiences at two speeds

Personal memory
Who has it
You, in every future session.
From when
The moment it is captured.
How
Recalled by search alongside the file and the table, with no review step.
Reviewed insight
Who has it
Everyone, once a reviewer applies it.
From when
After review, when it is promoted to a knowledge page or a catalog entity.
How
Durable business facts are captured with a type that enters the review queue, so a wrong claim cannot become team knowledge by accident.

The capture types and the review queue are covered in 206. What matters here is the choice of type. Facts about a supplier’s sheet are business knowledge for the team, so they are captured as business_knowledge rather than as a personal preference, which would never reach anyone else.

The capture in the portal

The Knowledge section of the portal shows both halves. Memory is the tab with what your agent has recorded for you; the review queue is where the durable captures wait; Knowledge is where the promoted pages live.

The portal’s Knowledge section on the Memory tab, listing captured memories with their type, confidence, and the session that recorded each one. — The capture as it appears in the portal’s Knowledge section, under Memory. It is already yours here. The review queue on the next tab is where it waits for the team.

Promoting the capture to a knowledge page

A reviewer with the role, or the reviewer’s agent, turns the queued insight into a knowledge page. The page is found or created by its slug, so a second promotion on the same topic updates the page rather than adding a duplicate. The promotion is recorded as a changeset and can be rolled back.

From a capture to a knowledge page

1
Search first
The reviewer’s agent searches the catalog and the knowledge pages for the topic, so the decision is update-or-create rather than blind-create. Nothing about a supplier price sheet existed yet.
2
Apply to a knowledge page
apply_knowledge with sink=knowledge_page, the insight id, and a page: slug supplier-price-sheet, title Blue Harbor Wholesale Price Sheet, a body in markdown, and two references, the scratch connection and the November dashboard asset.
3
The platform answers
Knowledge page created. References attached: 2. Insights marked applied: 1. The promotion is a changeset with an id, and it is revertible, so a page that turns out to be wrong can be rolled back rather than edited over.
4
Every agent recalls it
From the next session on, any teammate’s search for supplier cost, price sheet, or Blue Harbor returns the page beside the file and the table, and fetch reads it in full.

The page that resulted

The page carries more than the message you sent. The reviewer folded in what the first join surfaced, including a catalog data-quality issue that has nothing to do with the supplier, and a note on what to do when next month’s sheet arrives. It cites the scratch connection and the November dashboard as references, so a reader can follow the page to the table and to the work built on it.

The page as promoted, abridged

# Blue Harbor Wholesale Price Sheet

Blue Harbor Wholesale sends ACME a price sheet once a month. The current
sheet is the managed resource "Blue Harbor Wholesale price sheet", and it
is registered as scratch.uploads.admin_supplier_price_sheet on the scratch
connection, so it joins to the warehouse in ordinary SQL.

## Columns
| Column          | Meaning                                              |
| sku             | Matches warehouse.public.products.sku exactly.       |
| unit_cost       | Landed cost per unit in USD from effective_date.     |
| moq             | Minimum order quantity, in units.                    |
| effective_date  | First day the quoted cost applies, YYYY-MM-DD.       |
...

## How to read it
- Compare unit_cost against products.cost, the cost of record.
- Compare unit_cost against products.price for projected margin.
- A SKU absent from the sheet is one the supplier does not carry.
- Weight category figures by units sold in the period, not SKU count.
- Twelve products in the quoted range carry a cost of record above
  their shelf price. That is a catalog data-quality issue, not a
  supplier change; report it separately.

## When a new month's sheet arrives
The new file replaces the content of the same resource. The registered
table keeps reading the previous revision until it is registered again
under the same name; the Scratch Tables page reports it as Behind the
file until then.

The page says where the file is, what the table is called, what each column means, how to compare it, what a missing row means, and what to do next month. It is the message you sent the agent, made durable and cited. The data-quality note about twelve products is on the page because the first join surfaced it, and the next analyst should not rediscover it.

Knowledge pages in the portal

The page sits in the Knowledge section beside the other canonical pages for the business. Every agent on the deployment recalls it through search, and fetch reads it in full.

The portal’s Knowledge section on the Knowledge tab, listing canonical knowledge pages with their titles, summaries, tags, and the references each page cites. — Knowledge pages in the portal. A promoted page sits here beside the seasonality calendar and the returns policy, findable by search and readable by every agent connected to the deployment.

Recording the join as a reusable query

The capture in this lesson did one more thing: it cited the call that had just compared the quote to the cost of record. Every query and API call returns a call id, and citing one in a capture records that statement as reusable. The next person who asks the same question is offered the statement that already answered it.

The capture, with the call it cites

What the agent calls. This is the exchange the agent has with Plexara on your behalf, shown for the technical reader. You ask in plain language; you never type any of it.

memory_capture
  type        business_knowledge
  category    usage_guidance
  confidence  high
  sources     ["mcp:call:e-16onSTB…"]
  content     "Blue Harbor Wholesale sends a price sheet once a month ..."

-> id          bea60fc9ddaa8471421fe808b2b4098e
   sink_class  business_knowledge
   status      active
   message     "Captured. It will be reviewed before promotion to a shared catalog."

Every query and API call returns a call id. Citing it in sources records the statement as reusable, with your description of what it answers, and puts it up for promotion to the catalog. The next person who asks how the quote compares to the cost of record is offered the statement that already answered it, not a blank editor.

What a teammate’s agent sees the next morning

The test of all of this is a colleague who was not in the room. Their agent searches for the question, not the file. The result carries the file with its table and sample statement, the page that says what the columns mean, and the join that already worked.

What a teammate’s agent finds the next morning

search  intent="supplier cost vs cost of record"

resources
  Blue Harbor Wholesale price sheet (November 2025)
  mcp:resource:71131796b81fbb5641bdcbb3df0ef238
  table:
    connection   scratch
    query_table  scratch.uploads.admin_supplier_price_sheet
    sample_sql   SELECT * FROM scratch.uploads.admin_supplier_price_sheet
                 -- every column is VARCHAR, so a join to a typed column casts:
                 -- JOIN scratch.uploads.admin_supplier_price_sheet t ON w.id = CAST(t."sku" AS BIGINT)

knowledge_pages
  Blue Harbor Wholesale Price Sheet
  mcp:knowledge_page:kp_abbee77d-58f0-4789-b881-227d14f418d5
  "The monthly supplier quote: where the file lives, the table it is
   registered as, what each column means, how it joins ..."

calls
  Cost change and projected margin by category, November 2025
  mcp:call:e-16onSTB…

Three hits from one question, and none of them needed the teammate to know the file existed. The resource hit carries the table name and a sample statement, so finding the file and querying it are one turn apart. The knowledge page says what the columns mean. The recorded call is the join that already worked. The sample statement guesses the first column is the key and shows the cast pattern; the page corrects that for this file, where sku is text on both sides and unit_cost is the column that needs the cast.

Two halves of one integration

Registration and meaning are separate acts with separate audiences, and a file is integrated only when both are done. The whole of this lesson took about five minutes on the demo deployment, most of it spent typing the message.

Where this leads

With the file registered and understood, the work that was the point can start: the join, the figures, and the dashboard.

Key terms

Five terms from this lesson: the description on the file, the two states a capture passes through, the page it becomes, and the query it cites.

Key Terms

Description: The text on a resource that search matches. A file over 8 MB is found by its description and tags alone, so the description is what makes the file findable by the question somebody will ask.
Memorymemory_capture: A fact the agent records during a session. Live for you at once, and, for the durable types, queued for review before the team inherits it.
Insight: A captured memory of a durable type (business knowledge, an operational rule, a fact about a dataset) waiting in the review queue. Covered in 206.
Knowledge pageapply_knowledge sink=knowledge_page: A canonical page in the portal’s Knowledge section, found or created by slug, that every agent on the deployment recalls through search. The promotion is a revertible changeset.
Reusable query: A recorded call cited as the source of a capture. The statement is stored with your description of what it answers and offered to the next person who asks the same question.

503 - Teaching the agent what the file means