pm_knowledge

Sovereign

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.

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.

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.

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.

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

pm_knowledge {
  action: "get",
  scope: "project",
  projectId: "proj_checkout_01",
  includeDisabled: false
}

{
  "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
}

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

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"
    }
  ]
}

{
  "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"
    }
  ]
}

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.

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."
}

{
  "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."
    }
  }
}

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:

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"
}

Materialized Valdr Records

Use valdr_record_materialized for structured snapshots of Valdr records.

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"
}

{
  "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"
  }
}

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

pm_knowledge {
  action: "ingest",
  scope: "project",
  projectId: "proj_checkout_01",
  mode: "incremental",
  execution: "background"
}

{
  "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"
    }
  ]
}

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

pm_knowledge {
  action: "search",
  scope: "project",
  projectId: "proj_checkout_01",
  query: "refund retry escalation",
  retrievalMode: "hybrid",
  topK: 10,
  pathPrefixes: ["docs/runbooks"]
}

{
  "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
    }
  }
}

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

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"
}

{
  "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"
    }
  }
}

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.

code_map does not accept search-only controls such as retrievalMode, exactToken, offset, trustTiers, attachmentIds, or includeScoreBreakdown. Use search for those controls.

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

pm_knowledge {
  action: "status",
  scope: "project",
  projectId: "proj_checkout_01"
}

{
  "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"]
}

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.

pm_knowledge { action: "help" }

{
  "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."
  ]
}

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

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

pm_provider vmp (Valdr Mini-Planner)

pm_knowledge

Actions

Scope Model

Knowledge Sources

get

Parameters

Example

update_sources

Parameters

Operations

Example

record_entry

Parameters

Agent Memory Notebooks

Materialized Valdr Records

ingest

Parameters

Example

search

Parameters

Example

code_map

Query Patterns

Parameters

Example

status

Parameters

Example

help

Error Codes

Related