Tutorial 04: Understand entities, relations, and types

Continue from Tutorial 03 with the palmerpenguins repository open.

This tutorial explains how durmem structures what it remembers, so you can ask for exactly the facts you want and recognize when one is saved as the wrong kind of thing.

A few words first

An entity is one fact or thing durmem knows about, such as a Decision, a Roadmap item, or the Repo("palmerpenguins") node from Tutorial 03.
An entity's type says what it is. Decision and Roadmap are types; so are Repo and GitUser.
A relation is a typed link from one entity to another. PartOf links a repository to its project; Author links a fact to the person who wrote it.
A label is a small value node that many facts can point to, such as an importance level or a status. Pointing many facts at the same label is what lets one query find them all.
A unique label is a label a type allows only one of at a time. A Roadmap item has exactly one importance and at most one status, so changing either replaces the old value rather than adding a second one.

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.

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

1. Connect entities with relation edges

Tutorial 03's store view grouped facts by type. Now link two different kinds of fact to the same importance label, then use that label as the filter. The Roadmap item stays a Roadmap item; it only gets a different importance.

YouIn loom_demo, mark the Roadmap item "publish runnable onboarding demo for new agents" as important, and the Decision about reviewed tutorial changes as critical.

AgentThe agent finds those two existing facts. A Roadmap item always has exactly one importance (normal unless set), so the agent replaces its current normal value with important in one step. The Decision has no importance yet, so the agent adds critical. Neither fact is duplicated, and rerunning the request changes nothing.

ResultThe Roadmap item's importance changed from normal to Has() → Importance("important"). The Decision now has Has() → Importance("critical"). No duplicate items were created.

YouNow show important items in loom_demo.

AgentThe agent asks durmem for items marked important, critical, or roadblocker. Facts at normal priority are left out.

Illustrative outputThese example rows are not a live query result; the exact set depends on the current store.

Result

Important-or-higher items (important, critical, or roadblocker):
  - Goal: ship a private beta by September 30 [critical]
  - Roadmap: publish runnable onboarding demo for new agents [important]
  - Decision: small reviewed tutorial changes before live deploys [critical]

This illustration shows a Goal, a Roadmap item, and a Decision because each points to an importance label. Types keep what each fact is; shared relations let one query cross types.

2. Choose among the main loom-coding types

loom_demo comes with a small catalog of declared types rather than a blank slate. Most of what you touch day to day belongs to one of two families:

Record is history. A new entry is appended and the earlier one stays; nothing is overwritten. Decisions and Directives are Records.
Document is knowledge that is kept current, such as how a component works. When it changes, a newer version supersedes the older one, and the older one stays in the history; it is not edited in place.

A third family, Resource, holds things that are used or shared rather than written, such as a service you pay for. Tutorial 07 declares one, PaidService.

Choosing the right type makes recall precise: a standing instruction should surface as a Directive, while a measured result should stay a Finding.

YouList the concrete subtypes of Record and of CodeDoc (the coding-knowledge branch of Document) currently declared in loom_demo, with their descriptions.

AgentThe agent reads the live type catalog and groups the concrete types under their parent families.

Result

Record family (append-only history; the latest entry is what reads return):
  - Directive(statement)  — a standing rule/constraint the agent must follow
  - Decision(statement)   — a decision made, with rationale
  - Proposal(statement)   — a not-yet-decided design direction
  - HandoffTask(title)    — a repo-scoped next-session handoff note
  - Goal (abstract)       — durable objectives; a concrete subtype is declared
                            per kind, e.g. LearningGoal("Python") <: Goal

CodeDoc family (parent = CodeDoc <: Document; newer versions supersede older ones):
  - Architecture(title)   — how a component is built and why
  - AreaMap(title)        — WHERE a subsystem/business-function lives
  - BusinessContext(title)— why it exists / domain model / how code maps to value
  - Deliverable(title)    — a shipped artifact (skill, server, binary)
  - Environment(title)    — setup, versions, transport, paths, where state lives
  - Finding(title)        — a measured result, benchmark outcome, or dead-end
  - Glossary(title)       — a project-vocabulary term; definition lives in content
  - Mechanism(title)      — WHAT a code unit does / the invariant it enforces
  - Milestone(title)      — a named grouping of Roadmap items
  - Recipe(title)         — exact run/build/test how-to; commands live in content
  - Roadmap(title)        — planned-but-not-done work; conditions in content

Keep a few rules in mind as you browse the catalog:

Every fact is one entity plus its edges. Three edges you will see often are Author() for attribution and InScope() for scope (both from Tutorial 03), and IsAbout() for subject. IsAbout() points to a declared type, such as Release() or Deploy() under the DevOps family, never to a freeform string.
Has() → Importance("normal"|"important"|"critical"|"roadblocker") records priority. A fact with no Importance edge counts as normal. In the seeded schema, a Roadmap has exactly one Importance value (normal by default); that single-value constraint is not universal to every fact type. A fact type may declare its own single-value rule. Repeating a request does not raise importance, and roadblocker is reserved for blocking Roadmap work.
Has() → Status(...) is also a unique label on Roadmap items and Milestones. Changing it replaces the observed old value in one step, as in Tutorial 01.

You do not need to memorize this table. Ask durmem to show its types, or suggest the closest existing type, whenever you need one. The point is to know the families exist and roughly what each concrete type is for, so a Directive is not saved as a Finding by habit.

3. Takeaways