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 name and its persona field. A bare name (flaky-pool-drain-test) reaches agents in every workspace; {workspace}/{name} (backend/flaky-pool-drain-test) denominates the item under one workspace, where it is injected only into that workspace’s agents and is read and written through the workspace’s grants — like every other workspace-scoped resource. Set persona to narrow further to one persona, or leave it empty to reach every persona. In the dashboard, knowledge items are managed under Organization Settings → Knowledge, where the create form’s Workspace picker names the item. Agents give feedback on what they were shown: they bump items that materially helped and flag items that misled. A daily cull, configured by the knowledge-config singleton, prunes items that stop earning their keep because they were never bumped despite exposure, are stale after their last bump, or are actively harmful.

Fields

Name	Type	Required	Description
`workspace_use`	object	no	For tenant-level names, which workspaces may use this resource: `scope` is `WORKSPACE_USE_SCOPE_NONE` (default), `WORKSPACE_USE_SCOPE_ALL`, or `WORKSPACE_USE_SCOPE_SELECTED` with a `workspaces` list. Scoped names carry no policy and are usable only in their own workspace. See resource admission.
`name`	string	yes	A bare tenant-level DNS label (`flaky-pool-drain-test`, `[a-z][a-z0-9-]{0,62}`), whose injection follows `workspace_use`, or `{workspace}/{name}` (`backend/flaky-pool-drain-test`) for one existing workspace. Fixed after creation.
`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.
`persona`	string	no	Persona scope. Empty = applies to every persona. Must resolve to a usable agent-persona, as it would for an agent spawned in the item’s workspace: `{workspace}/{persona}` first, then the bare name.
`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.
`when_to_use`	string	no	Situations, tasks, or observable symptoms where this knowledge changes what an agent should do. Discovery information, not a scope or exclusion rule. Maximum 1 KiB.
`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 backend/flaky-pool-drain-test
---
title: "TestPoolDrain is flaky under -race"
summary: "TestPoolDrain fails ~5% of runs under -race; retry once before investigating."
persona: murmur-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 items usable in the agent’s workspace and matching its persona into a reference-numbered block. Scoped items match only their own workspace; tenant-level items also need admission through workspace_use. The block is 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 get knowledge

The list prints one name per line, with no header.

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 prints on stdout. 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`	`knowledge name must be a DNS label or {workspace}/{name}`	Use a bare DNS-label name, or prefix it with an existing workspace’s name and `/`.
`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`	`when_to_use exceeds 1024 byte limit (N bytes)`	Shorten `when_to_use` to 1 KiB or fewer.
`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 name’s `{workspace}/` prefix names a workspace that does not exist.
`PERMISSION_DENIED`	`workspace.use`	The item is named under a workspace whose grants do not admit you. Ask a workspace manager for access.
`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.
`FAILED_PRECONDITION`	`knowledge "<name>" is referenced in see_also by <names>; remove those references first`	Returned by `murmur rm knowledge`. Remove the item from the other items’ `see_also` lists first.
`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 an item can be named under
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