--- title: "Context sets and pins" description: "Curating what an agent gets at start_session: always-load pins, reusable cross-space context sets, and memory muting." --- # Context sets and pins When an agent calls `start_session`, it doesn't get the whole knowledge base — it gets the starting context you curate. The **Agents → Context** section is a builder for that starting context: here you decide exactly what the agent sees at the start — which notes always load (pins), which reusable bundles are attached to a scope (context sets), and which memory categories are muted. Tag pins and memory muting are file-first: they live in note frontmatter and survive a re-clone of the repository. Context sets and cross-space pins are stored in the metadata database (a deliberate caveat: neither a re-clone onto a clean host nor the `none` mode will preserve them). ## Always-load pins A pin is a manual "always load" mark (membership in the `always-load` tag, not ordering). Pins work along two axes: - **Personal** — notes in your personal domain go into `profile.alwaysLoad` and load on **every** session. - **Project** — notes in the subtree of a marked project go into `project.alwaysLoad` and load when the agent is working **in that project** (the `project` hint). A pin is tied to where the note lives: a note in the personal domain pins into the profile, a note in a project subtree pins into the project bundle. The builder shows exactly what the agent will actually load — curation on the server and in the preview runs through the same code. ## Context sets — cross-space bundles The `always-load` tag ties a pin to a single space. Context sets remove that limit: a context set is a **named, reusable collection of note references** that you can attach to another scope. A typical scenario: you assemble a "Frontend conventions" set from notes in the shared `conventions` space and attach it to projects in a different space. Every session of those projects gets these notes, and you edit the set in one place — it updates everywhere. There's also a lighter option — the **cross-space loose pin**: a single note pinned directly into a scope from another space, without a set wrapper. The `always-load` tag stays for same-space pins; sets and loose pins are for cross-space. They all coexist, and dedup is by note-id. > [!note] Ownership ≥ attachment > A set lives in its home space, and membership there grants visibility and edit access. A personal set attaches only to your personal domain; a shared set (from a shared space) attaches to your personal domain or to any project. You can't attach a personal set to a project — it would load context only for you. ## Order = load priority The order of pins and sets in the list is yours (drag-and-drop), not derived. It sets priority: what's higher loads first and is trimmed last when you hit the token budget. Pins and sets share a single ranked list (you can move a set above a pin). The overall load order is **pins → sets → memory** (specific outweighs general), then the overflow is trimmed to the scope's budget. ## Memory muting (mute) Agent memory loads into context by default. If a category is noisy, mute it selectively (`mute`). Muting removes that memory from everywhere it reaches the agent on its own, without an explicit request: - the personal profile, which loads right at `start_session`; - the `recall` bundle assembly; - the category dictionary in `start_session(project).knownValues`. > [!important] Search sees muted memory on purpose > `search` does **not** filter out muted memory: it indexes memory precisely for the "search before you write" dedup. Otherwise the agent wouldn't find a muted category and would recreate a duplicate. Muting silences auto-context; it isn't deletion: explicit search and audit still see everything. The reverse is `Unmute` on the same axis. ## A single token budget Above the builder's sections there's one load gauge, exactly matching the current scope's budget. A personal response has one budget (pins first, then memory); a project response has its own budget, where project pins come first and the personal background fits into what's left. What's loaded is always ≤ the budget, and trimming is visible item by item. Project memory doesn't load right away — it's pulled in on request; if a specific project fact is always needed, pin the note. ## Next - [Retrieval audit](/docs/agents/audit/) — the builder's twin at runtime: what the agent actually pulls. - [Agent memory](/docs/agents/memory/) — how the memory you mute is built. - [Agent rules](/docs/agents/agent-files/) — the other half of the job: making sure `start_session` gets called at all. - [Intent tools](/docs/agents/intent-tools/) — `start_session` and the rest of the tools.