> ## Documentation Index
> Fetch the complete documentation index at: https://docs.murmur.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# knowledge catalog resource

> Catalog resource holding one unit of curated fleet lore — a short note injected into matching agents' prompts, plus optional long-form pulled on demand.

A **knowledge item** is one curated, reviewable unit of fleet lore. Its `summary` is injected verbatim into matching [agents'](/concepts/agents) prompts every turn; the optional `details` long form is pulled on demand with [`murmur get`](/cli/get) (or `catalog_get` from an agent). Humans and agents write items directly — every write is an audited revision — or stage them as [change-requests](/catalog/change-request) when human review is wanted before injection.

An item is scoped by its `workspace` and `persona` fields: set either (or both) to narrow which agents see it, or leave both empty to reach every agent in the tenant. In the dashboard, knowledge items are managed under **Organization Settings → Knowledge**.

Agents give feedback on what they were shown: they **bump** items that materially helped and **flag** items that misled, and a daily **cull** (configured by the [knowledge-config](#cull-configuration-knowledge-config) singleton) prunes items that stop earning their keep — never bumped despite exposure, stale after their last bump, or actively harmful.

## Fields

| Name         | Type      | Required | Description                                                                                                                                                                                  |
| ------------ | --------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`       | string    | yes      | Unique name within the tenant (e.g. `flaky-pool-drain-test`). DNS label format: `[a-z][a-z0-9-]{0,62}`.                                                                                      |
| `content`    | string    | no       | Server-rendered full Markdown (frontmatter + body). Ignored on input when structured fields are present; regenerated on every write. Provide `content` alone to author the item as Markdown. |
| `title`      | string    | yes      | One-line label serving list UIs. Never injected into prompts, so a title-only edit resets no harm signals. Maximum 1024 bytes.                                                               |
| `summary`    | string    | yes      | The short form: plain Markdown injected verbatim into matching agents' prompts every turn. Maximum 1 KiB.                                                                                    |
| `workspace`  | string    | no       | [Workspace](/concepts/workspaces) scope. Empty = applies in every workspace. Must name an existing workspace.                                                                                |
| `persona`    | string    | no       | [Persona](/concepts/agent-personas) scope. Empty = applies to every persona. Must resolve to a usable [agent-persona](/catalog/agent-persona).                                               |
| `see_also`   | string\[] | no       | Names of related knowledge items, rendered as cross-references in the injected block. Validated at write time; an item referenced by a surviving item is exempt from culling.                |
| `created_at` | timestamp | no       | Server-set on create and preserved across edits; never client-writable. The cull clock starts here.                                                                                          |
| `details`    | string    | no       | The long form: the Markdown body after frontmatter, stored verbatim. Maximum 64 KiB. When non-empty the injected block marks the item truncated and agents pull it on demand.                |

## Input formats

### Markdown with frontmatter

Pipe a Markdown file where the YAML frontmatter carries the structured fields and the body is the `details` long form.

```bash theme={null}
cat <<'EOF' | murmur set knowledge flaky-pool-drain-test
---
title: "TestPoolDrain is flaky under -race"
summary: "TestPoolDrain fails ~5% of runs under -race; retry once before investigating."
workspace: backend
persona: programmer
see_also:
  - pool-reaper-dry-run
---
The flake is a lost wakeup in the drain barrier: under -race the reaper
goroutine can observe the pool as empty before the final release lands.
A retry masks it; the real fix is tracked in #3121.
EOF
```

### Structured fields

Post individual fields as YAML. `details` carries the long form directly.

```bash theme={null}
cat <<'EOF' | murmur set knowledge flaky-pool-drain-test
name: flaky-pool-drain-test
title: "TestPoolDrain is flaky under -race"
summary: "TestPoolDrain fails ~5% of runs under -race; retry once before investigating."
EOF
```

## Injection, bumps, and flags

Every turn, the platform resolves the items matching the agent's workspace and persona into a reference-numbered block (budgeted at 64 KiB; lowest-bump items are omitted first when it overflows):

```
[1] flaky-pool-drain-test — TestPoolDrain fails ~5% of runs under -race. (truncated — full text: catalog_get kind="knowledge" name="flaky-pool-drain-test") (see also: [2])
[2] pool-reaper-dry-run — The stranded-workflow reaper defaults to dry_run.
```

At the end of its turn the agent reports the reference numbers that materially helped (**bumps**) and flags items that were stale or misleading with a one-sentence reason (**flags**). Feedback is generation-scoped: bumps and flags recorded against an edited wording don't carry over to the rewrite, and an edit to `summary`, `details`, or `see_also` clears the item's accumulated flags.

## Cull configuration (knowledge-config)

The `knowledge-config` kind is a tenant singleton (name `default`, like [pool-config](/catalog/pool-config)) configuring the daily cull. When the resource is absent, built-in defaults apply. When it exists, every field is required and every threshold must be in `[1, 36500]`.

| Name                | Type   | Default   | Description                                                                                                                                            |
| ------------------- | ------ | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `cull`              | string | `dry_run` | `dry_run` (log candidates only), `enabled` (delete candidates), or `disabled` (no candidate computation; the per-round flag-triage report still runs). |
| `min_age_days`      | int32  | `30`      | Days since the last content edit before an item is cullable on the exposure/staleness branches. Must be in `[1, 36500]`.                               |
| `min_injections`    | int32  | `20`      | Exposures (injections + budget omissions) required before zero bumps counts against an item. Must be in `[1, 36500]`.                                  |
| `max_unbumped_days` | int32  | `90`      | Days since the last bump before a previously-bumped item goes stale. Must be in `[1, 36500]`.                                                          |
| `min_flags`         | int32  | `3`       | Flags required before a net-negative item (flags > same-version bumps) is culled as actively harmful. Must be in `[1, 36500]`.                         |

```bash theme={null}
cat <<'EOF' | murmur set knowledge-config default
cull: enabled
min_age_days: 30
min_injections: 20
max_unbumped_days: 90
min_flags: 3
EOF
```

## Examples

### Listing knowledge items

```bash theme={null}
murmur ls knowledge
```

### Reading a single item

```bash theme={null}
murmur get knowledge flaky-pool-drain-test
```

The response is the server-rendered Markdown — YAML frontmatter followed by the `details` body.

### Proposing an edit for human review

Agents (and cautious humans) can stage a write as a [change-request](/catalog/change-request) instead of applying it directly:

```bash theme={null}
cat flaky-pool-drain-test.md | murmur set knowledge flaky-pool-drain-test --propose --rationale "flake rate doubled since #3121"
```

The new change-request id is printed; apply it later with `murmur change-request approve <id>`.

### Deleting a knowledge item

```bash theme={null}
murmur rm knowledge flaky-pool-drain-test
```

## Errors

| Code               | Meaning                                                            | What to do                                                                                       |
| ------------------ | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------ |
| `INVALID_ARGUMENT` | `name must match [a-z][a-z0-9-]{0,62}`                             | Use a bare DNS-label name.                                                                       |
| `INVALID_ARGUMENT` | `title is required`                                                | Provide a one-line `title`.                                                                      |
| `INVALID_ARGUMENT` | `title exceeds 1024 byte limit (N bytes)`                          | Shorten `title` to 1024 bytes or fewer.                                                          |
| `INVALID_ARGUMENT` | `summary is required`                                              | Provide the injected short form in `summary`.                                                    |
| `INVALID_ARGUMENT` | `summary exceeds 1024 byte limit (N bytes)`                        | Shorten `summary` to 1 KiB or fewer; move depth into `details`.                                  |
| `INVALID_ARGUMENT` | `details exceeds 65536 byte limit (N bytes)`                       | Shorten `details` to 64 KiB or fewer.                                                            |
| `INVALID_ARGUMENT` | `either content or structured fields are required`                 | The request is empty. Provide `content` (Markdown with frontmatter) or structured fields.        |
| `INVALID_ARGUMENT` | `parse knowledge content: ...`                                     | The Markdown frontmatter failed to parse as valid YAML. Check your `---` fences and YAML syntax. |
| `INVALID_ARGUMENT` | `workspace "<name>" does not exist`                                | The `workspace` scope names a [workspace](/concepts/workspaces) that does not exist.             |
| `INVALID_ARGUMENT` | `persona "<name>" does not exist`                                  | The `persona` scope names no [agent-persona](/catalog/agent-persona).                            |
| `INVALID_ARGUMENT` | `persona "<name>" does not resolve to a usable agent persona`      | Reference a usable [agent-persona](/catalog/agent-persona).                                      |
| `INVALID_ARGUMENT` | `see_also must not reference the item itself`                      | Remove the self-reference from `see_also`.                                                       |
| `INVALID_ARGUMENT` | `see_also knowledge "<name>" does not exist`                       | Every `see_also` entry must name an existing knowledge item. Create it first or fix the name.    |
| `INVALID_ARGUMENT` | `cull must be "dry_run", "enabled", or "disabled" (got "<value>")` | Use one of the three cull modes on `knowledge-config`.                                           |
| `INVALID_ARGUMENT` | `<threshold> must be positive (got N)`                             | Every `knowledge-config` threshold must be strictly positive.                                    |
| `INVALID_ARGUMENT` | `<threshold> must be at most 36500 (got N)`                        | Every `knowledge-config` threshold is capped at `36500`.                                         |

## Related

* [agent-persona](/catalog/agent-persona) — the persona scope an item can target
* [Workspaces](/concepts/workspaces) — the workspace scope an item can target
* [change-request](/catalog/change-request) — the review path for proposed knowledge edits
* [pool-config](/catalog/pool-config) — the other tenant-singleton config kind, same conventions as `knowledge-config`
* [`murmur set`](/cli/set) — CLI command for creating and updating catalog resources
* [`murmur get`](/cli/get) — CLI command for reading catalog resources