Workspace Knowledge

Workspace Knowledge is the place where Valdr turns your local repos, docs, and agent memory into usable context for real agent work. Instead of pasting the same architecture notes into every session, you attach the sources once, index them, and give agents a searchable local map of the workspace they are operating in.

This is where the control plane becomes visible: which sources are attached, how fresh they are, how much code and documentation has been indexed, and whether the code graph is rich enough for symbol-aware investigation.

Workspace Knowledge turns attached local context into inspectable, agent-ready source awareness

What this page covers

• Reading Workspace Knowledge health metrics
• Attaching and managing indexed sources
• Using the Query Console for ranked retrieval
• Using Code Map to trace definitions, references, tests, and impact
• Knowing when to rebuild, disable, or remove a source

Overview

The Overview tab answers the first operational question: “Can my agents trust the context they are about to use?”

At the top, metric cards summarize the current scope:

Use these cards before launching a knowledge-heavy agent session. A healthy source list means the agent can retrieve targeted evidence instead of spending prompt budget rediscovering repo structure.

Source Table

The source table is the inventory for your local knowledge layer. Each row is an attached source, and each column gives you an operator signal:

Use the scope selector to switch between all knowledge, project-specific knowledge, or an explicit project set. Use the filter box to narrow by source name, trust tier, or kind when the table gets large.

Trust Tiers

Trust tiers shape retrieval priority. They are not just labels.

Put stable project docs and source roots in canonical. Keep temporary observations in memory so agents can still find them without outranking more authoritative context.

Details Panel

Select a source to open the Details panel. This is where you verify whether an attachment is usable before handing it to an agent.

The resource section shows:

• Type: Docs or Code Intelligence
• Freshness: Whether Valdr expects sweep-only checks or deeper re-ingest work
• Index status: Ready, stale, failed, or disabled
• Chunks: Searchable chunk count
• Latest run: Most recent ingest result
• Updated: Last observed update date

The action buttons let you run incremental ingest, rebuild the source, disable retrieval, or remove the attachment. Use incremental ingest for ordinary refreshes. Use rebuild when the underlying extractor, parser, or code graph behavior changed and you need a full re-index.

Graph Metrics

The Graph tab shows whether Valdr has enough reference data to support code navigation, not just plain-text search.

Graph metrics reveal how much of the workspace can be navigated as real code relationships

A higher target link rate means Code Map can answer deeper questions: where something is defined, who calls it, which tests exercise it, and what else changes when it moves.

Query Console

Use the Query Console when you need ranked evidence: code excerpts, docs snippets, memory notes, and source provenance in one feed.

Search across indexed local context and inspect ranked evidence before an agent acts on it

The default retrieval mode is designed for practical investigation:

• Auto/hybrid retrieval balances lexical and semantic matches when available.
• Knowledge type filters let you include docs, code intelligence, or both.
• Trust tier filters keep searches scoped to canonical, operational, or memory sources.
• Language filters narrow code-heavy searches to the language you care about.
• Result scores and badges show why a hit is likely relevant.

Good query examples:

HttpClient
sanitize FTS
provider preset export
agent memory notebook

Use Query Console to gather evidence before you launch an agent, or to verify what an agent will be able to retrieve through the pm_knowledge search action.

Code Map

Use Code Map when the question is structural. Instead of asking for prose search, ask Valdr to navigate the code graph.

Code Map turns source-aware questions into a navigable graph of definitions, references, tests, and related files

Strong Code Map prompts are intent-shaped:

definition of StringUtils
references to Future
callers of parseConfig
imports of HttpClientOptions
tests for CacheManager
docs for deployment runbooks

Code Map reports how many results were returned, omitted, or excluded by intent. That matters during review: you can tell whether the graph found a focused answer or whether your query needs a narrower symbol, language, or path.

Map View

Map view is the fastest way to understand relationships around a symbol. The center node is your query target. Connected nodes show files, modules, tests, docs, and related sources, with edge labels such as definition, reference, test, or related.

Use it when you need to answer:

• Where is this symbol defined?
• Which files reference it?
• Are the tests close to the implementation?
• Does this relationship cross source roots or projects?

Impact View

Impact view flattens graph results into a reviewable list of files and hit counts.

Impact view converts graph traversal into a practical file list for review and implementation planning

Use Impact view before changing a shared type, utility, API, or behavior. It gives you a quick file-by-file inventory so you can plan implementation and tests without manually searching every repo.

Trace View

Trace view turns a query into a flow: target symbol, source roots, modules, tests, and related files.

Trace view shows how a symbol moves across sources, modules, tests, and related code paths

Use Trace when you need to retarget the investigation. Click a node to make it the new center, then keep following the chain. This is the high-leverage workflow for agents and humans: start with a symbol, inspect its real dependencies, then decide what work is safe to delegate.

Recommended Workflow

When To Use Each Surface

Next Steps

Read the Workspace Knowledge feature guide for the product-level model, then use the pm_knowledge MCP reference to give agents the same search and code-map power from their own sessions.