# pm_knowledge
{{< badge content="Sovereign" color="purple" class="tier-badge" >}}

{{< callout type="info" >}}
**Sovereign tier required.** Workspace Knowledge is an advanced MCP surface because it lets agents attach local sources, index code, search persistent workspace context, and record durable memory.
{{< /callout >}}

The `pm_knowledge` tool turns Valdr's Workspace Knowledge layer into an agent-callable surface. Agents can attach docs and code, queue ingestion, search across project and global context, record durable notes, and ask symbol-shaped questions such as "definition of HttpClientBuilder" or "callers of parseConfig".

Use this tool when an agent needs more than the current prompt window. `pm_knowledge` lets teams keep canonical docs, operational runbooks, indexed source trees, Valdr records, and Agent Memory Notebooks available as structured retrieval instead of re-explaining the same context in every session.

{{< callout type="info" >}}
Project-scoped sources must live inside one of the project's repository roots. Global sources are for shared workspace context and are guarded against over-broad or sensitive filesystem paths.
{{< /callout >}}

{{< callout type="warning" >}}
**Symbol-aware code intelligence currently supports TypeScript/TSX and Java.** The `search` action can still retrieve indexed code chunks from other languages, but `code_map` symbol resolution, references, and graph traversal are only expected for TypeScript/TSX and Java sources right now.
{{< /callout >}}

## Actions

`get`, `update_sources`, `record_entry`, `ingest`, `search`, `code_map`, `status`, `help`

---

## Scope Model

Most read actions can target one project, several projects, global Workspace Knowledge, or everything.

| Scope | Use for |
|-------|---------|
| `project` | One project's attached knowledge sources |
| `projects` | An explicit set of project IDs |
| `global` | Workspace-wide knowledge not owned by one project |
| `all` | Project and global knowledge together |

`scope: "project"` requires `projectId`. `scope: "projects"` requires `projectIds`. `update_sources` and `record_entry` write to either `project` or `global` because every attachment belongs to one scope.

## Knowledge Sources

`update_sources` can attach these source shapes:

| Knowledge type | Resource kind | Typical use |
|----------------|---------------|-------------|
| `docs` | `folder` | Product docs, architecture notes, runbooks |
| `code_intelligence` | `folder` | Source trees for code search and code map |

`attachment:file`, `url:url`, and `code_intelligence:file` are compatibility values for older persisted rows. They are not current public attach modes.

`record_entry` manages first-class records instead:

| Entry type | Purpose |
|------------|---------|
| `agent_knowledge` | Agent Memory Notebooks for durable per-agent notes |
| `valdr_record_materialized` | Materialized Valdr records such as task snapshots |

Trust tiers influence ranking:

| Trust tier | Typical source |
|------------|----------------|
| `canonical` | First-party docs, primary specs, official project guidance |
| `operational` | Runbooks, operator notes, project references |
| `memory` | Agent Memory Notebook entries, draft observations, lower-confidence context |

---

## get

List knowledge attachments and their underlying resources for a scope.

### Parameters

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `scope` | string | Yes | `project`, `projects`, `global`, or `all` |
| `projectId` | string | Conditional | Required when `scope` is `project` |
| `projectIds` | string[] | Conditional | Required when `scope` is `projects` |
| `includeDisabled` | boolean | No | Include disabled attachments |

### Example

{{< tabs >}}
{{< tab name="Request" selected=true >}}
```text
pm_knowledge {
  action: "get",
  scope: "project",
  projectId: "proj_checkout_01",
  includeDisabled: false
}
```
{{< /tab >}}
{{< tab name="Response" >}}
```json
{
  "scope": "project",
  "attachments": [
    {
      "id": "att_checkout_docs",
      "resourceId": "res_checkout_docs",
      "scopeType": "project",
      "scopeId": "proj_checkout_01",
      "projectKey": "acme-checkout",
      "trustTier": "canonical",
      "rankingWeight": 1,
      "enabled": true,
      "label": "Checkout Runbooks"
    },
    {
      "id": "att_checkout_src",
      "resourceId": "res_checkout_src",
      "scopeType": "project",
      "scopeId": "proj_checkout_01",
      "projectKey": "acme-checkout",
      "trustTier": "operational",
      "rankingWeight": 0.8,
      "enabled": true,
      "label": "Checkout Service Source"
    }
  ],
  "resources": [
    {
      "id": "res_checkout_docs",
      "knowledgeType": "docs",
      "resourceKind": "folder",
      "displayName": "Checkout Runbooks",
      "canonicalLocator": "file:///Users/me/dev/acme-checkout/docs/",
      "indexStatus": "ready",
      "chunkCount": 36
    },
    {
      "id": "res_checkout_src",
      "knowledgeType": "code_intelligence",
      "resourceKind": "folder",
      "displayName": "Checkout Service Source",
      "canonicalLocator": "file:///Users/me/dev/acme-checkout/services/checkout/src/",
      "indexStatus": "ready",
      "chunkCount": 128,
      "languages": ["ts", "tsx"]
    }
  ],
  "staleCount": 0,
  "failedCount": 0
}
```
{{< /tab >}}
{{< /tabs >}}

Returns attachment summaries, resource summaries, and stale/failed counts.

Project-scoped attachment summaries include `projectKey` alongside the stable `scopeId`. `projectKey` is only a readable convenience field; `scopeId` remains the canonical project identifier.

---

## update_sources

Add, remove, enable, disable, or update source attachments for a project or global scope.

### Parameters

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `scope` | string | Yes | `project` or `global` |
| `projectId` | string | Conditional | Required when `scope` is `project` |
| `operations` | array | Yes | One or more source operations |

### Operations

| Operation | Required fields | Notes |
|-----------|-----------------|-------|
| `add` | `knowledgeType`, `resourceKind`, `locator` | Optional `label`, `trustTier`, `rankingWeight`, `enabled` |
| `remove` | `attachmentId` | Detaches the source from the scope |
| `enable` | `attachmentId` | Re-enables retrieval from the attachment |
| `disable` | `attachmentId` | Keeps the attachment but excludes it by default |
| `update` | `attachmentId` plus one mutable field | Can update `label`, `trustTier`, `rankingWeight`, or `enabled` |

### Example

{{< tabs >}}
{{< tab name="Request" selected=true >}}
```text
pm_knowledge {
  action: "update_sources",
  scope: "project",
  projectId: "proj_checkout_01",
  operations: [
    {
      op: "add",
      knowledgeType: "code_intelligence",
      resourceKind: "folder",
      locator: "file:///Users/me/dev/acme-checkout/services/checkout/src",
      label: "Checkout Service Source",
      trustTier: "operational"
    }
  ]
}
```
{{< /tab >}}
{{< tab name="Response" >}}
```json
{
  "scope": "project",
  "projectId": "proj_checkout_01",
  "operations": [
    {
      "op": "add",
      "status": "attached",
      "attachmentId": "att_checkout_src",
      "resourceId": "res_checkout_src"
    }
  ],
  "attachments": [
    {
      "id": "att_checkout_src",
      "resourceId": "res_checkout_src",
      "scopeType": "project",
      "scopeId": "proj_checkout_01",
      "projectKey": "acme-checkout",
      "trustTier": "operational",
      "rankingWeight": 1,
      "enabled": true,
      "label": "Checkout Service Source"
    }
  ],
  "resources": [
    {
      "id": "res_checkout_src",
      "knowledgeType": "code_intelligence",
      "resourceKind": "folder",
      "displayName": "Checkout Service Source",
      "canonicalLocator": "file:///Users/me/dev/acme-checkout/services/checkout/src",
      "indexStatus": "stale"
    }
  ]
}
```
{{< /tab >}}
{{< /tabs >}}

Source policy rejects sensitive paths, over-broad global folders, unsupported source shapes, and project-scoped paths outside the project's repository roots.

---

## record_entry

Create, update, delete, or append managed knowledge records that are written through `record_entry` instead of `update_sources`.

### Parameters

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `mode` | string | Yes | `create`, `update`, `delete`, or `append` |
| `entryType` | string | Yes | `agent_knowledge` or `valdr_record_materialized` |
| `scope` | string | Yes | `project` or `global` |
| `projectId` | string | Conditional | Required when `scope` is `project` |
| `entryId` | string | Conditional | Required for update/delete |
| `title` | string | No | Entry or note title |
| `body` | string | No | Entry body |
| `trustTier` | string | No | Defaults by entry type |
| `rankingWeight` | number | No | `0.1` to `2.0` |
| `metadata` | object | No | Caller-defined metadata |

### Agent Memory Notebooks

Use `mode: "append"` with `entryType: "agent_knowledge"` to add a note to one Agent Memory Notebook per agent per scope.

{{< tabs >}}
{{< tab name="Request" selected=true >}}
```text
pm_knowledge {
  action: "record_entry",
  mode: "append",
  entryType: "agent_knowledge",
  scope: "project",
  projectId: "proj_checkout_01",
  agentHandle: "checkout-reviewer",
  title: "Reviewer memory",
  body: "Prefer the mock gateway contract when testing refunds."
}
```
{{< /tab >}}
{{< tab name="Response" >}}
```json
{
  "entry": {
    "id": "entry_checkout_reviewer_notes",
    "entryType": "agent_knowledge",
    "scopeType": "project",
    "scopeId": "proj_checkout_01",
    "agentHandle": "checkout-reviewer",
    "title": "Checkout reviewer notebook",
    "trustTier": "memory",
    "rankingWeight": 0.7,
    "noteCount": 3,
    "latestNote": {
      "id": "note_checkout_reviewer_003",
      "title": "Reviewer memory",
      "body": "Prefer the mock gateway contract when testing refunds."
    }
  }
}
```
{{< /tab >}}
{{< /tabs >}}

Agent handles are normalized to lowercase. `create` and `update` are not valid for `agent_knowledge`; append adds memory, delete removes a notebook or a specific note.

Delete one note from a notebook:

{{< tabs >}}
{{< tab name="Request" selected=true >}}
```text
pm_knowledge {
  action: "record_entry",
  mode: "delete",
  entryType: "agent_knowledge",
  scope: "project",
  projectId: "proj_checkout_01",
  entryId: "entry_checkout_reviewer_notes",
  noteId: "note_checkout_reviewer_002"
}
```
{{< /tab >}}
{{< tab name="Response" >}}
```json
{
  "deleted": true,
  "entryId": "entry_checkout_reviewer_notes",
  "noteId": "note_checkout_reviewer_002",
  "remainingNoteCount": 2
}
```
{{< /tab >}}
{{< /tabs >}}

### Materialized Valdr Records

Use `valdr_record_materialized` for structured snapshots of Valdr records.

{{< tabs >}}
{{< tab name="Request" selected=true >}}
```text
pm_knowledge {
  action: "record_entry",
  mode: "create",
  entryType: "valdr_record_materialized",
  scope: "project",
  projectId: "proj_checkout_01",
  recordType: "task",
  recordId: "CHECKOUT-42",
  recordVersion: 1,
  title: "Refund retry acceptance snapshot",
  body: "Acceptance notes for retry behavior and alert routing.",
  trustTier: "canonical"
}
```
{{< /tab >}}
{{< tab name="Response" >}}
```json
{
  "entry": {
    "id": "entry_checkout_task_42_v1",
    "entryType": "valdr_record_materialized",
    "scopeType": "project",
    "scopeId": "proj_checkout_01",
    "recordType": "task",
    "recordId": "CHECKOUT-42",
    "recordVersion": 1,
    "title": "Refund retry acceptance snapshot",
    "trustTier": "canonical",
    "rankingWeight": 1,
    "indexStatus": "stale"
  }
}
```
{{< /tab >}}
{{< /tabs >}}

---

## ingest

Queue resources for extraction, chunking, embedding, and code graph indexing.

### Parameters

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `scope` | string | No | Defaults to `all` when no explicit IDs are provided |
| `projectId` | string | Conditional | Required when `scope` is `project` |
| `attachmentIds` | string[] | No | Ingest exact attachments |
| `resourceIds` | string[] | No | Ingest exact resources |
| `mode` | string | No | `incremental` default, or `rebuild` |
| `execution` | string | No | `inline` default, or `background` |

Selection precedence is `attachmentIds`, then `resourceIds`, then the resolved scope.

### Example

{{< tabs >}}
{{< tab name="Request" selected=true >}}
```text
pm_knowledge {
  action: "ingest",
  scope: "project",
  projectId: "proj_checkout_01",
  mode: "incremental",
  execution: "background"
}
```
{{< /tab >}}
{{< tab name="Response" >}}
```json
{
  "scope": "project",
  "projectId": "proj_checkout_01",
  "mode": "incremental",
  "execution": "background",
  "queued": true,
  "runId": "ingest_checkout_20260524_01",
  "targets": [
    {
      "attachmentId": "att_checkout_docs",
      "resourceId": "res_checkout_docs",
      "status": "queued"
    },
    {
      "attachmentId": "att_checkout_src",
      "resourceId": "res_checkout_src",
      "status": "queued"
    }
  ]
}
```
{{< /tab >}}
{{< /tabs >}}

`incremental` skips unchanged resources. `rebuild` re-extracts every chunk and refreshes derived indexes. `background` returns immediately while Valdr drains the ingest queue; `inline` waits for the run to finish.

---

## search

Run filtered keyword or prose retrieval across indexed docs, records, notes, and code chunks.

### Parameters

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `query` | string | Yes | Search text |
| `scope` | string | No | `project`, `projects`, `global`, or `all` |
| `projectId` / `projectIds` | string / string[] | Conditional | Required for project scopes |
| `topK` | number | No | `1` to `50`, default `10` |
| `offset` | number | No | Pagination offset |
| `retrievalMode` | string | No | `auto`, `lexical`, `semantic`, or `hybrid` |
| `knowledgeTypes` | string[] | No | Filter by source type |
| `resourceKinds` | string[] | No | Filter by physical source shape |
| `trustTiers` | string[] | No | Filter by trust tier |
| `languages` | string[] | No | Filter code chunks by language |
| `symbolKinds` | string[] | No | Filter code chunks by symbol kind |
| `pathPrefixes` | string[] | No | Accepts `file://`, absolute, or project-relative prefixes |
| `exactToken` | boolean | No | Require whole-token matches |
| `enabledOnly` | boolean | No | Defaults to `true` |
| `includeContent` | boolean | No | Include full chunk text in `hits[].content` |
| `includeScoreBreakdown` | boolean | No | Legacy diagnostics switch; prefer `responseProfile: "debug"` |
| `responseProfile` | string | No | `compact`, `debug`, or `full`; compact is the default |

### Example

{{< tabs >}}
{{< tab name="Request" selected=true >}}
```text
pm_knowledge {
  action: "search",
  scope: "project",
  projectId: "proj_checkout_01",
  query: "refund retry escalation",
  retrievalMode: "hybrid",
  topK: 10,
  pathPrefixes: ["docs/runbooks"]
}
```
{{< /tab >}}
{{< tab name="Response" >}}
```json
{
  "scope": "project",
  "retrievalModeRequested": "hybrid",
  "retrievalModeUsed": "hybrid",
  "embeddingModelKeyUsed": "local-code-token",
  "semanticSearchAvailable": true,
  "semanticUnavailableReasons": [],
  "offsetUsed": 0,
  "topKUsed": 10,
  "totalHitCount": 2,
  "truncated": false,
  "responseProfile": "compact",
  "hits": [
    {
      "resourceId": "res_checkout_docs",
      "chunkId": "chunk_checkout_runbook_017",
      "title": "Refund Retry Runbook",
      "excerpt": "Escalate refund retries after the third gateway timeout and page the checkout owner if settlement is blocked.",
      "knowledgeType": "docs",
      "resourceKind": "folder",
      "sourceLabel": "Checkout Runbooks",
      "lineStart": 22,
      "lineEnd": 34,
      "score": 0.91,
      "effectiveAttachmentId": "att_checkout_docs",
      "attachmentIds": ["att_checkout_docs"]
    },
    {
      "resourceId": "res_checkout_docs",
      "chunkId": "chunk_checkout_runbook_018",
      "title": "Refund Retry Runbook",
      "excerpt": "Use the mock gateway contract for replay tests before enabling live refund retries.",
      "knowledgeType": "docs",
      "resourceKind": "folder",
      "sourceLabel": "Checkout Runbooks",
      "lineStart": 35,
      "lineEnd": 47,
      "score": 0.86,
      "effectiveAttachmentId": "att_checkout_docs",
      "attachmentIds": ["att_checkout_docs"]
    }
  ],
  "attachments": {
    "att_checkout_docs": {
      "id": "att_checkout_docs",
      "resourceId": "res_checkout_docs",
      "scopeType": "project",
      "scopeId": "proj_checkout_01",
      "projectKey": "acme-checkout",
      "label": "Checkout Runbooks",
      "enabled": true
    }
  }
}
```
{{< /tab >}}
{{< /tabs >}}

Compact search hits include excerpts, source ids, line ranges when available, scores, and optional full content. Use `responseProfile: "debug"` or `"full"` for ranking reasons, score breakdowns, and expanded attachment diagnostics. When semantic retrieval is unavailable, the response reports why in `semanticUnavailableReasons`.

Compact search responses keep hits small by hoisting attachment summaries into an `attachments` map. Project-scoped attachment summaries include `projectKey`; hits refer to them by `effectiveAttachmentId` or `attachmentIds`.

---

## code_map

Run symbol-oriented graph navigation grouped by role. Use this when the query is about definitions, callers, references, imports, tests, or docs for a symbol.

### Query Patterns

| Intent | Pattern examples |
|--------|------------------|
| Definition | `definition of HttpClientBuilder`, `where is ConnectionPool defined` |
| References | `references to Future`, `where do we use RequestContext` |
| Callers | `callers of parseConfig`, `who calls normalizeRequest` |
| Imports/exports | `imports of HttpClientOptions`, `exports ConnectionPool` |
| Tests | `tests for CacheManager`, `where is retryPolicy tested` |
| Docs | `docs for deployment runbooks`, `documentation for release checklist` |

Plain prose falls back to retrieval grouping. Rephrase into one of the patterns above when graph navigation matters.

### Parameters

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `query` | string | Yes | Symbol or graph-intent query |
| `scope` | string | No | `project`, `projects`, `global`, or `all` |
| `projectId` / `projectIds` | string / string[] | Conditional | Required for project scopes |
| `topK` | number | No | Overall hit target |
| `knowledgeTypes` | string[] | No | Filter source/result hits |
| `resourceKinds` | string[] | No | Filter source/result hits |
| `languages` | string[] | No | Filter by chunk language |
| `symbolKinds` | string[] | No | Filter source/result symbol kinds |
| `pathPrefixes` | string[] | No | Filter returned hits by path |
| `responseProfile` | string | No | `compact` default, `debug`, or `full` |
| `includeDiagnostics` | boolean | No | Infer `debug` when profile is omitted |
| `includeContent` | boolean | No | Include chunk content |
| `includeRawRetrieval` | boolean | No | Include raw flat retrieval payload |
| `maxTotalHits` | number | No | Cap grouped hits |
| `maxHitsPerGroup` | number | No | Cap each role group |

### Example

{{< tabs >}}
{{< tab name="Request" selected=true >}}
```text
pm_knowledge {
  action: "code_map",
  scope: "project",
  projectId: "proj_checkout_01",
  query: "definition of PaymentRetryPolicy",
  languages: ["ts"],
  pathPrefixes: ["services/checkout/src"],
  topK: 20,
  responseProfile: "compact"
}
```
{{< /tab >}}
{{< tab name="Response" >}}
```json
{
  "query": "definition of PaymentRetryPolicy",
  "intent": "definition",
  "inferredIntent": "definition",
  "target": "PaymentRetryPolicy",
  "responseProfile": "compact",
  "graph": {
    "symbols": true,
    "references": true
  },
  "usingPersistedSymbols": true,
  "usingPersistedReferences": true,
  "groupOrder": ["definition", "related", "doc", "test", "reference", "import", "export", "unknown"],
  "groups": {
    "definition": [
      {
        "resourceId": "res_checkout_src",
        "chunkId": "chunk_checkout_policy_001",
        "title": "PaymentRetryPolicy",
        "symbolName": "PaymentRetryPolicy",
        "symbolKind": "class",
        "language": "ts",
        "path": "services/checkout/src/retry/payment-retry-policy.ts",
        "lineStart": 14,
        "lineEnd": 68,
        "excerpt": "class PaymentRetryPolicy selects retry windows for card, ACH, and wallet refund attempts."
      }
    ],
    "test": [
      {
        "resourceId": "res_checkout_src",
        "chunkId": "chunk_checkout_policy_test_002",
        "title": "PaymentRetryPolicy retry limits",
        "symbolKind": "test",
        "language": "ts",
        "path": "services/checkout/src/retry/payment-retry-policy.test.ts",
        "lineStart": 21,
        "lineEnd": 46,
        "excerpt": "verifies that retry attempts stop before manual-review escalation."
      }
    ]
  },
  "groupCounts": {
    "definitions": { "total": 1, "returned": 1, "omitted": 0, "intentExcluded": 0 },
    "references": { "total": 4, "returned": 0, "omitted": 4, "intentExcluded": 4 },
    "imports": { "total": 2, "returned": 0, "omitted": 2, "intentExcluded": 2 },
    "exports": { "total": 1, "returned": 0, "omitted": 1, "intentExcluded": 1 },
    "tests": { "total": 1, "returned": 1, "omitted": 0, "intentExcluded": 0 },
    "docs": { "total": 1, "returned": 0, "omitted": 1, "intentExcluded": 1 },
    "related": { "total": 2, "returned": 0, "omitted": 2, "intentExcluded": 2 }
  },
  "omitted": {
    "diagnostics": true,
    "content": true,
    "rawRetrieval": true
  },
  "resources": {
    "res_checkout_src": {
      "displayName": "Checkout Service Source",
      "knowledgeType": "code_intelligence",
      "resourceKind": "folder"
    }
  }
}
```
{{< /tab >}}
{{< /tabs >}}

The response groups hits into `definitions`, `references`, `imports`, `exports`, `tests`, `docs`, and `related`. It also reports whether persisted symbol and reference graphs were used, so agents can distinguish graph-backed answers from retrieval fallback.

{{< callout type="warning" >}}
`code_map` does not accept search-only controls such as `retrievalMode`, `exactToken`, `offset`, `trustTiers`, `attachmentIds`, or `includeScoreBreakdown`. Use `search` for those controls.
{{< /callout >}}

---

## status

Fetch knowledge health counters for a scope. This is the quickest way to see whether sources have been ingested and whether code graph data exists.

### Parameters

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `scope` | string | No | Defaults to `all` |
| `projectId` / `projectIds` | string / string[] | Conditional | Required for project scopes |
| `profile` | string | No | `summary` or `full` |

### Example

{{< tabs >}}
{{< tab name="Request" selected=true >}}
```text
pm_knowledge {
  action: "status",
  scope: "project",
  projectId: "proj_checkout_01"
}
```
{{< /tab >}}
{{< tab name="Response" >}}
```json
{
  "profile": "full",
  "scope": "project",
  "resourceCount": 2,
  "attachmentCount": 2,
  "entryCount": 2,
  "chunkCount": 164,
  "codeChunkCount": 128,
  "docsChunkCount": 36,
  "codeResourceCount": 1,
  "docsResourceCount": 1,
  "symbolCount": 842,
  "referenceCount": 1934,
  "resolvedReferenceCount": 811,
  "unresolvedReferenceCount": 1123,
  "crossResourceReferenceCount": 18,
  "symbolKindCounts": {
    "function": 502,
    "method": 119,
    "class": 26,
    "interface": 18
  },
  "referenceKindCounts": {
    "call": 1477,
    "import": 211,
    "type": 188,
    "export": 58
  },
  "staleCount": 0,
  "failedCount": 0,
  "watchingCount": 0,
  "sweepOnlyCount": 2,
  "activeEmbeddingModel": "local-code-token",
  "indexedLanguages": ["ts", "tsx"]
}
```
{{< /tab >}}
{{< /tabs >}}

Returns counts for resources, attachments, entries, chunks, code chunks, docs chunks, symbols, references, stale resources, failed resources, indexed languages, and the active embedding model.

---

## help

Return the canonical help payload from the MCP server.

{{< tabs >}}
{{< tab name="Request" selected=true >}}
```text
pm_knowledge { action: "help" }
```
{{< /tab >}}
{{< tab name="Response" >}}
```json
{
  "actions": ["get", "update_sources", "record_entry", "ingest", "search", "code_map", "status", "help"],
  "whenToUse": {
    "search": "Filtered keyword or prose retrieval across docs, records, and code chunks.",
    "code_map": "Symbol-oriented code navigation grouped into definitions, references, callers, imports, tests, docs, and related code."
  },
  "queryPatterns": [
    "definition of <symbol|FQN>",
    "references to <symbol|FQN>",
    "callers of <symbol|FQN>",
    "imports of <symbol|FQN>",
    "tests for <symbol>",
    "docs for <symbol>"
  ],
  "examples": {
    "search": [
      {
        "action": "search",
        "params": {
          "query": "refund retry escalation",
          "pathPrefixes": ["docs/runbooks"],
          "retrievalMode": "hybrid",
          "topK": 10
        }
      }
    ],
    "code_map": [
      {
        "action": "code_map",
        "params": {
          "scope": "project",
          "query": "definition of PaymentRetryPolicy",
          "topK": 10
        }
      }
    ]
  },
  "cautions": [
    "search defaults to compact output; request debug or full only for diagnostics.",
    "code_map does not accept search-only controls such as retrievalMode, exactToken, offset, trustTiers, attachmentIds, or includeScoreBreakdown."
  ]
}
```
{{< /tab >}}
{{< /tabs >}}

Use this when building an agent capability around Workspace Knowledge. The help payload includes actions, query patterns, examples, cautions, and the docs path emitted by the running server.

## Error Codes

Common knowledge errors:

| Code | Meaning |
|------|---------|
| `KNOWLEDGE_INVALID_LOCATOR` | Locator was not valid or could not be inspected |
| `KNOWLEDGE_PROJECT_REQUIRED` | Project scope was missing a project ID |
| `KNOWLEDGE_SOURCE_OUTSIDE_PROJECT` | Project source was outside the project's repo roots |
| `KNOWLEDGE_SOURCE_TOO_BROAD` | Global folder pointed at a system root or broad home/tmp path |
| `KNOWLEDGE_SOURCE_TOO_LARGE` | Folder exceeded the source file limit |
| `KNOWLEDGE_SENSITIVE_SOURCE` | Source matched a sensitive path or credential filename |
| `KNOWLEDGE_UNSUPPORTED_SOURCE_TYPE` | Resource kind/type is not supported by the ingest path |
| `KNOWLEDGE_RESOURCE_NOT_FOUND` | Targeted resource ID does not exist |
| `KNOWLEDGE_ATTACHMENT_NOT_FOUND` | Targeted attachment ID does not exist |
| `KNOWLEDGE_INGEST_TARGET_REQUIRED` | Ingest had no resolvable target |
| `KNOWLEDGE_RECORD_ENTRY_MODE_REQUIRED` | `record_entry` was missing `mode` |
| `KNOWLEDGE_UNKNOWN_ACTION` | Unknown action name |

## Related

- [Workspace Knowledge feature guide](/valdr/docs/features/knowledge/) - product-level overview of workspace context, search, code map, and Agent Memory Notebooks workflow
- [pm_project](../projects/) - projects provide the repo roots used by project-scoped knowledge
- [pm_task](../tasks/) - tasks can be materialized into durable knowledge records
- [pm_agent](../agents/) - agents can record and later retrieve scoped notebook memory
- [pm_health](../health/) - verify the running MCP server and available tool inventory