knowledge catalog resource

A knowledge item is one curated, reviewable unit of fleet lore. Its summary is injected verbatim into matching agents’ prompts every turn; the optional details long form is pulled on demand with murmur 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 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 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 scope. Empty = applies in every workspace. Must name an existing workspace.
`persona`	string	no	Persona scope. Empty = applies to every persona. Must resolve to a usable 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.

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.

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) 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]`.

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

murmur ls knowledge

Reading a single item

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 instead of applying it directly:

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

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 that does not exist.
`INVALID_ARGUMENT`	`persona "<name>" does not exist`	The `persona` scope names no agent-persona.
`INVALID_ARGUMENT`	`persona "<name>" does not resolve to a usable agent persona`	Reference a usable 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`.

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

Getting Started

Core Concepts

Guides

knowledge catalog resource

Fields

Input formats

Markdown with frontmatter

Structured fields

Injection, bumps, and flags

Cull configuration (knowledge-config)

Examples

Listing knowledge items

Reading a single item

Proposing an edit for human review

Deleting a knowledge item

Errors

​Fields

​Input formats

​Markdown with frontmatter

​Structured fields

​Injection, bumps, and flags

​Cull configuration (knowledge-config)

​Examples

​Listing knowledge items

​Reading a single item

​Proposing an edit for human review

​Deleting a knowledge item

​Errors

​Related

Fields

Input formats

Markdown with frontmatter

Structured fields

Injection, bumps, and flags

Cull configuration (knowledge-config)

Examples

Listing knowledge items

Reading a single item

Proposing an edit for human review

Deleting a knowledge item

Errors

Related