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

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.

{{< thumbcard src="/images/ui/knowledge/workspace-knowledge-overview.png" alt="Workspace Knowledge overview showing source metrics, attached knowledge sources, and a selected source details panel" caption="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

{{< callout type="info" >}}
**Local-first:** Workspace Knowledge runs against sources in your local Valdr workspace. Attached sources, indexed chunks, code graph data, and memory records remain under your control until you remove them.
{{< /callout >}}

{{< callout type="warning" >}}
**Symbol-aware code intelligence currently supports TypeScript/TSX and Java.** Other source files can still be indexed for code chunk retrieval and text search, but symbol counts, resolved references, and Code Map graph results are only expected for TypeScript/TSX and Java sources right now.
{{< /callout >}}

---

## 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:

| Metric | What it tells you |
|--------|-------------------|
| **Sources Indexed** | How many enabled attachments are in the selected scope |
| **Code Chunks** | Searchable source-code chunks available for retrieval |
| **Symbols** | Persisted definitions that support code navigation |
| **References** | Calls, imports, and type edges available for graph traversal |
| **Docs Indexed** | Documentation chunks available beside code |
| **Needs Attention** | Stale, failed, disabled, or otherwise unhealthy sources |

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:

| Column | Why it matters |
|--------|----------------|
| **Source** | The readable label and locator for the repo, docs folder, or indexed path |
| **Tier** | Ranking trust: canonical, operational, or memory |
| **Kind** | Whether the source is docs or code intelligence |
| **Status** | Whether indexing is ready, stale, failed, or disabled |
| **Chunks** | How much searchable material came from the source |
| **Updated** | When Valdr last refreshed the attachment |

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.

| Tier | Use it for |
|------|------------|
| **Canonical** | First-party docs, source roots, official specs, primary implementation references |
| **Operational** | Runbooks, working notes, repo-specific operator guidance |
| **Memory** | Agent Memory Notebook entries, discoveries, and lower-confidence working context |

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.

{{< callout type="tip" >}}
Before a deep agent investigation, check the selected source status and chunk count. If the source is stale or empty, refresh it first so the agent does not waste a run on outdated context.
{{< /callout >}}

---

## Graph Metrics

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

{{< thumbcard src="/images/ui/knowledge/workspace-knowledge-graph-metrics.png" alt="Workspace Knowledge graph metrics showing target link rate, linked references, text-only references, cross links, and top reference kind" caption="Graph metrics reveal how much of the workspace can be navigated as real code relationships" >}}

| Metric | What it means |
|--------|---------------|
| **Target Link Rate** | Percent of references that resolved to a persisted target symbol |
| **Linked Refs** | References with a concrete target definition |
| **Text-Only Refs** | Searchable reference text that did not resolve to a symbol |
| **Cross Links** | References crossing source files |
| **Top Ref Kind** | The most common relationship type, such as calls |

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.

{{< thumbcard src="/images/ui/knowledge/workspace-knowledge-query-console.png" alt="Workspace Knowledge Query Console showing a search for HttpClient and ranked code intelligence results" caption="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:

```text
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.

{{< thumbcard src="/images/ui/knowledge/workspace-knowledge-code-map-map.png" alt="Code Map graph showing references to StringUtils connected to related source files" caption="Code Map turns source-aware questions into a navigable graph of definitions, references, tests, and related files" >}}

Strong Code Map prompts are intent-shaped:

```text
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.

{{< thumbcard src="/images/ui/knowledge/workspace-knowledge-code-map-impact.png" alt="Code Map Impact view showing files affected by references to Future with hit and file counts" caption="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.

{{< thumbcard src="/images/ui/knowledge/workspace-knowledge-code-map-trace.png" alt="Code Map Trace view showing references to Future across Vertx, Netty, Valdr Services, and Commons Lang sources" caption="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

{{% steps %}}

### Attach the right sources

Attach project source roots and docs folders that matter for the work. Keep broad, unrelated folders out of scope so retrieval stays precise.

### Confirm health

Check Overview metrics, source status, chunk counts, and latest ingest runs. Fix stale or failed sources before relying on search.

### Search for evidence

Open Query Console for ranked excerpts when you need source snippets, docs, notes, or provenance.

### Map code relationships

Open Code Map for definitions, references, callers, imports, tests, docs, and impact analysis.

### Launch with context

Use the results to brief yourself or launch an agent with confidence that it can retrieve the same local context through `pm_knowledge`.

{{% /steps %}}

## When To Use Each Surface

| Need | Use |
|------|-----|
| Verify source freshness | Overview and Details panel |
| Check graph richness | Graph metrics |
| Find ranked snippets | Query Console |
| Follow definitions or references | Code Map - Map |
| Plan a change across files | Code Map - Impact |
| Explore cross-source flow | Code Map - Trace |
| Automate from an agent | [`pm_knowledge`](/valdr/docs/valdr-mcp/knowledge/) |

## Next Steps

Read the [Workspace Knowledge feature guide](/valdr/docs/features/knowledge/) for the product-level model, then use the [`pm_knowledge` MCP reference](/valdr/docs/valdr-mcp/knowledge/) to give agents the same search and code-map power from their own sessions.