Tutorial 03: Set up project memory

This tutorial prepares the palmerpenguins repository for project memory: who authors facts, which project they belong to, and how a later session finds them. Later coding-memory tutorials build on it.

Complete Tutorial 00, Tutorial 01, and Tutorial 02 first.

Three meanings of "workspace"

The word appears in three places. They are related but not the same thing:

• Your harness workspace is the folder your coding agent has open, here the cloned demo folder.
• A durmem Workspace is a node in the store that groups projects, one level above a project in the scope chain of §3.
• A workspace mapping is an optional [workspace.<name>] entry in ~/.loom/stores.toml that tells this computer which store holds coding memory for one workspace. §4 adds one only if you choose to.

Start here: make loom_demo the session default

1. Verify the tutorial repository and store

Continue in the palmerpenguins repository you opened in Tutorial 00. If it is not the current harness workspace, return to Tutorial 00 and complete its first step.

The repository says which work a memory belongs to; the store says where it is kept. Verify both before creating facts so later sessions read from the same place.

If loom_demo is missing, sign in again with durmem login (for a private server, durmem login --base https://durmem.ai) and stop here if it is still missing. Do not use an unrelated store just because its name looks close.

2. Resolve your author identity

durmem attributes every fact to a real author, so a shared store stays trustworthy when several developers use it. The author identity comes from git, not from a name you type.

An edge can point only to a node that already exists, which is why the identity node comes before any fact that names its author.

Saving a fact that already exists returns the existing fact and leaves its original author unchanged. If a tutorial fact was saved earlier under another author, the agent should say so rather than claim it was re-attributed.

If git config user.email is empty, belongs to a CI system, or is otherwise not the identity you intend, fix it before saving anything. A wrong email creates a second author that never matches your real history.

3. Build the scope chain

Tutorial 01 recalled memory by naming a project, and that is all a first recall needs. Coding work benefits from more structure: a fact about one repository should also see the rules that apply to its whole project or organization. durmem does this with a scope chain of four nodes, each PartOf the next:

Repo("palmerpenguins")
  PartOf → Project("palmerpenguins")
    PartOf → Workspace("palmerpenguins")
      PartOf → Organization("loom-tutorials")

A fact is filed at one node with an InScope() edge. A read at a node also includes facts filed at its ancestors, so a repository-level read sees project-, workspace-, and organization-wide facts. Reads follow PartOf upward only: reading at Organization("loom-tutorials") does not return facts filed under the project below it. File each fact at the narrowest node that fits, and read from the node where you are working.

Then tell future sessions where they are. Without this, a new agent may infer the repository name but miss the project, workspace, and organization, and its automatic reads would return only repository context:

4. Optional: map this workspace to loom_demo

So far each tutorial session has started with a prompt that makes loom_demo the session default. A workspace mapping makes that choice persistent for this one workspace. It is an explicit opt-in that edits your private ~/.loom/stores.toml. It is optional for ordinary coding, but the hook exercise in Tutorial 06 requires it, so do it before that tutorial; otherwise keep the per-session prompt.

To undo it, ask the agent to remove only that [workspace.palmerpenguins] entry.

5. See what is already in the store

Before saving project facts, ask for a bounded view of the whole store. It shows both the data you expected and anything you did not know was there, without letting one large type flood the answer.

Decision (2):
  - small reviewed tutorial changes before live deploys
  - use the existing notification service for invitation emails

Directive (2):
  - ask before pushing origin main
  - keep access bundles local

GitUser (1):
  - dev1@gmail.com

Goal (1):
  - ship a private beta by September 30 [critical]

Organization (1):
  - loom-tutorials

Project (3):
  - durmem practice notebook
  - loom_demo
  - palmerpenguins

Repo (1):
  - palmerpenguins

Roadmap (2):
  - finish invitation emails before the beta [done]
  - publish runnable onboarding demo for new agents [in_flight]

Workspace (1):
  - palmerpenguins

Read this as "the store includes at least these", not as an exact report. The Directives, the onboarding Roadmap item, and the reviewed-changes Decision are sample facts the store started with, under Project("loom_demo"). The Goal, the invitation-email items, and durmem practice notebook come from Tutorial 01. The identity and scope nodes come from §2 and §3. Counts grow as you work through later tutorials, and a rerun shows facts from earlier passes.

This view shows only populated types. Tutorial 04 shows the full list of declared types, including ones with no facts yet. To see only one project's facts, ask for that project explicitly.

6. Takeaways

• "Workspace" means three things: your harness folder, a durmem Workspace node, and an optional stores.toml mapping.
• Resolve author identity from git config user.email, never from a typed-in name.
• Create a node before any edge that points to it; rerunning get-or-create setup is safe.
• The Repo -> Project -> Workspace -> Organization chain lets a read include facts from wider scopes. File each fact at the narrowest node that fits.
• A workspace mapping is optional and persistent; add it only if you want it.
• Start with a bounded view of the whole store, then narrow to a project when needed.
• Continue to Tutorial 04: Understand entities, relations, and types.