> For the complete documentation index, see [llms.txt](https://docs.visdom.virtuslab.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.visdom.virtuslab.com/visdom-tracing/user-guide/context-flows-labels-and-params.md).

# Context: flows, labels and params

`tracevault context` manages the metadata that the agent hook stamps on **every** captured event: a flow ID, a set of labels, and arbitrary key/value params. This is what drives grouping and filtering in the Flows view and the analytics UI. Without it the ledger is a pile of sessions; with it, sessions belong to a named piece of work.

## Three layers, low → high precedence

```
user  →  repo (global)  →  worktree
```

* **User**: optional, cross-repo, opt-in. Lives outside the repo (by default `~/.config/tracevault/context.json`), so it follows *you* across every project instead of being scoped to one.
* **Repo (global)**: `.tracevault/context.json`, shared by every worktree of the repository.
* **Worktree**: `.tracevault/worktrees/<key>/context.json`, present only inside a linked git worktree.

More specific wins. For `flow_id` and for each `params` key, the highest layer that sets a value takes precedence: worktree beats repo beats user. **Labels behave differently**: they are a union across every present layer. There is no cross-layer removal of a label; `--remove-label` only removes it from the file you are editing.

{% hint style="info" %}
Params support a **tombstone**. `context update --remove-param KEY` records `KEY = null` in that layer's file instead of deleting the key. The null propagates through the merge and drops a value inherited from a lower layer, which is the only way to unset something the user layer set. Values dropped this way are simply absent from `context show`.
{% endhint %}

## Enabling the user layer: `user_context` in `config.toml`

The user layer is off by default for compatibility: a `config.toml` without the field, or with `user_context = false`, never consults one. `tracevault init` enables it for newly initialised projects (`--no-user-context` to opt out, `--user-context <path>` to point it somewhere explicit).

| `config.toml`                                           | Meaning                                              |
| ------------------------------------------------------- | ---------------------------------------------------- |
| `user_context = false`, or field absent                 | disabled, no user layer is consulted                 |
| `user_context = true`                                   | enabled, reading `~/.config/tracevault/context.json` |
| `user_context = "/custom/path.json"`                    | enabled, reading that file                           |
| `[user_context]` with `enable = false` / `path = "..."` | disabled, but remembers a path for later re-enabling |

Change it afterwards with `tracevault context source`. Exactly one mode flag is required.

```bash
tracevault context source --enable                  # on, at the default path
tracevault context source --path ~/team-ctx.json    # on, reading a custom file
tracevault context source --default                 # on, and reset to the default path
tracevault context source --disable                 # off
```

## Editing each layer

`context set` replaces the saved context entirely: omitted dimensions are left empty, so labels and params you do not re-specify are cleared. `context update` merges: it sets `--flow`, unions `--label`, inserts or overwrites `--param`, and removes `--remove-label` / `--remove-param` entries. `context clear` empties the file.

All three act on the repo or worktree file by scope: the per-worktree file by default inside a linked worktree, `--global` to force the repo-wide file from anywhere. Pass `--user` on any of them to target the resolved user-context file instead, whatever the worktree scope.

```bash
# Cross-repo defaults, set once
tracevault context source --path ~/.config/tracevault/context.json
tracevault context set --user --label solo-dev --param editor=nvim

# Per-repo, per-task
tracevault context set --flow add-payment-retry --label payments --label backend
tracevault context update --param env=staging --remove-label backend
tracevault context show
tracevault context clear
```

`tracevault context show` prints every layer that is present (User, Global, This worktree) and then an **Effective** section that annotates each flow, label and param with the layer it resolved from. Reach for it whenever a value did or did not win and it is not obvious why.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.visdom.virtuslab.com/visdom-tracing/user-guide/context-flows-labels-and-params.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.