Tutorial 07: Create a custom type

Continue from Tutorial 06 with [loom_demo] loaded.

Loom does not require you to design a schema up front. An agent first checks the live catalog for a suitable type, declares a reusable custom type only when the catalog lacks one, verifies its fields, and then saves structured facts. This tutorial uses project subscriptions because their names, monthly costs, and effective dates make the value of a strongly typed memory immediately visible.

Rerun note: every save below is idempotent. A rerun reuses the existing declaration and facts rather than duplicating them.

Start here: make `loom_demo` the session default

YouLoad the configured store named loom_demo and make it the default for this session only. Confirm the effective session default, and do not edit ~/.loom/stores.toml.

AgentThe agent connects to the existing loom_demo store and changes only this session's default routing.

Resultloom_demo is now the default for this session. Persistent configuration was not changed.

1. Check before creating a type

YouIn [loom_demo], I want to track paid services for this project, including each service's name, monthly cost, and the date that price became effective. Check whether a suitable type already exists before creating one.

AgentThe agent inspects the closest existing types and compares their purpose, parent, fields, and descriptions. The ranking is evidence to review, not an automatic verdict. If a compatible PaidService declaration already exists, the agent reuses it; otherwise it explains why the nearby types do not represent the same reusable shape.

ResultNo existing type has the required service, monthly-cost, and effective-date shape, so a reusable PaidService type is justified. On a rerun, I found the existing compatible declaration and will reuse it.

This check prevents a catalog from accumulating near-duplicates such as separate types for AWS costs, editor subscriptions, and hosting plans. The kind is a paid service; the individual service belongs in the data.

2. Declare and verify `PaidService`

YouIf it is not declared yet, create PaidService as a resource with exactly these fields in this order: name, monthly_cost, and asof. Then read the declaration back before saving anything.

AgentThe agent declares the custom type when needed, including a short justification from the reuse check, and then reads the live declaration back to verify its parent and field order.

Result[loom_demo] declares PaidService(name, monthly_cost, asof) under Resource. The readback confirms exactly those three fields in that order, with no hidden field. The type is available immediately; no server restart or migration is needed.

Readback matters before a bulk save: field names and order are part of the strongly typed contract that every connected agent will share.

3. Save structured paid-service facts

YouRemember these paid services for this project. I learned all four prices on April 1, 2026, and each price was effective that same day: AWS costs $340 per month for hosting, OpenAI costs $120 for API access, Cursor costs $60 for three editor seats, and Vercel costs $20 for frontend hosting.

AgentThe agent saves four PaidService facts with known_from = 2026-04-01, asof = 2026-04-01, the verified fields, the current git user as author, and the current project scope. It then reads the saved rows back as typed data.

ResultThe four baseline rows are stored in [loom_demo]:

name	monthly_cost	asof
AWS	$340	April 1, 2026
OpenAI	$120	April 1, 2026
Cursor	$60	April 1, 2026
Vercel	$20	April 1, 2026

The custom type follows the same author and scope discipline as every built-in type. Once declared, it also joins the catalog that future agents inspect before proposing another type.

4. Calculate a total from typed fields

YouWhat is the monthly total across those four exact baseline facts, before applying any later corrections?

AgentThe agent reads the four baseline rows and sums their monthly_cost fields.

ResultThe baseline total is $540 per month: AWS $340 + OpenAI $120 + Cursor $60 + Vercel $20.

This is structured aggregation from typed fields, not a search for an old prose answer.

5. Update a price without erasing history

Cursor raises its price to $96 per month on May 20, 2026, but the project does not learn about it until July 1, 2026.

YouCursor raised its price to $96 per month on May 20, 2026, but I did not notice until July 1, 2026. Update the price without erasing the previous value.

AgentThe agent saves the new Cursor row with May 20, 2026 as its effective date and July 1, 2026 as the date the information became known. It marks the new row as replacing the exact $60 row, which remains available in history.

ResultCursor's current price is $96 per month, effective May 20, 2026 and known from July 1, 2026. The former $60 price remains in history as a once-valid value that was superseded.

YouWhat did I believe the monthly total was as of June 1, 2026, and what did the recorded lifecycle show after I learned about the Cursor change?

AgentThe agent compares the store's June 1, 2026 knowledge with the later lifecycle stage and avoids counting both Cursor rows.

ResultOn June 1, 2026, the known total was $540 because the $96 Cursor price was not learned until July. After learning the change, the recorded total became $576: AWS $340 + OpenAI $120 + Cursor $96 + Vercel $20.

The date a fact becomes known and the date a price becomes effective answer different questions. Typed fields preserve both.

6. Correct a fact that was never true

YouAfter July 1, 2026, I realized Vercel was never $20 per month. The correct price has been $25 since April 1, 2026, and I learned this on July 2, 2026. Correct it without deleting the audit trail.

AgentThe agent saves the corrected Vercel row and marks the exact $20 row as false, rather than treating it as a formerly valid price.

ResultVercel's current price is $25 per month, effective April 1, 2026 and known from July 2, 2026. The $20 row remains in history as a negated claim that was never true.

A superseded fact was valid before a real change. A negated fact was incorrect from the start. Preserving that distinction explains the history instead of merely retaining old numbers.

7. Compare current, belief-time, and effective-time answers

YouWhat is the current total, what did I believe on June 1, 2026, and what do I now know was actually effective on June 1, 2026? Explain the retired rows.

AgentThe agent reads the current rows, reconstructs the June 1, 2026 knowledge view, evaluates the effective dates, and follows the retirement reasons for the former Cursor and Vercel rows.

ResultThe current total is $581 per month: AWS $340 + OpenAI $120 + Cursor $96 + Vercel $25. On June 1, 2026, the known total was $540 because both corrections were learned in July. The prices now known to have been effective on June 1, 2026 total $581. Cursor $60 was superseded by a real price change; Vercel $20 was negated because it was never correct.

One custom type now supports discovery, strongly typed storage, aggregation, current-state reads, and two kinds of historical reasoning. That is the standard for a useful custom type: it captures a reusable kind of information rather than one isolated fact.

8. Takeaways

Check the live catalog before declaring a type; judge candidates by meaning, parent, fields, and description.
Put the reusable kind in the type and the specific service in a field.
Read a new declaration back before saving multiple facts.
A custom type uses the same author and scope discipline as built-in types.
Calculate from typed fields instead of cached prose.
Keep belief time separate from a domain-effective date.
Preserve whether an old value was superseded by change or negated as false.
Continue to Tutorial 08: Plan with past decisions.