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

Most AI agents lose context between sessions and across repositories. Workspace Knowledge gives Valdr agents persistent awareness of your codebase, docs, decisions, and operational context so they can investigate, plan, and review work without starting from zero every time.

It turns prompt-driven workers into **workspace-aware engineering operators**.

> This is the difference between an agent that asks you where everything lives and an agent that can do the first deep dive itself.

## What changes

Without Workspace Knowledge, every agent run starts with the same tax: explain the repo layout, paste the relevant docs, describe the architecture, mention the hidden gotchas, then hope the agent keeps it all straight.

With Workspace Knowledge, agents can begin by searching the workspace itself. They can inspect attached repos, find relevant docs, trace definitions and references, pull prior decisions from memory, and bring that context into execution, review, or audit.

That means fewer repeated context handoffs, fewer review cycles spent reconstructing intent, and less token budget burned on rediscovering what your team already knows.

{{< cards >}}
  {{< card title="Agents stop wasting cycles" subtitle="They retrieve project docs, source context, operational notes, and previous discoveries before they act" icon="search" >}}
  {{< card title="Deep dives span projects" subtitle="Agents can follow definitions, callers, references, tests, docs, and related code across attached sources" icon="code" >}}
  {{< card title="Context compounds" subtitle="Agent Memory Notebooks preserve useful findings so the next session does not rediscover them" icon="clipboard-list" >}}
  {{< card title="Sessions get smarter" subtitle="Launched agents start with richer context and can keep searching while they work" icon="terminal" >}}
{{< /cards >}}

{{< callout type="info" >}}
**Sovereign tier required.** Workspace Knowledge is a Sovereign feature because it gives agents persistent context, cross-project source navigation, and Agent Memory Notebooks instead of relying only on the current prompt.
{{< /callout >}}

{{< callout type="warning" >}}
**Symbol-aware code intelligence currently supports TypeScript/TSX and Java.** Other languages can still be useful as indexed code chunks for retrieval, but symbols, resolved references, and Code Map graph traversal are only expected for TypeScript/TSX and Java sources right now.
{{< /callout >}}

## What agents can now do

Workspace Knowledge is not just a place to store files. It changes the work agents can reliably perform.

| Agent goal | What Workspace Knowledge enables |
|------------|----------------------------------|
| Understand a system before editing | Search project docs, source trees, runbooks, and Agent Memory Notebook entries before proposing changes |
| Trace impact across repos | Find definitions, references, imports, exports, callers, tests, docs, and related files |
| Review with real context | Pull source, task, and prior decision context into reviewer and auditor sessions |
| Preserve discoveries | Append useful findings to scoped memory so future sessions inherit them |
| Reduce prompt and review overhead | Retrieve targeted evidence instead of pasting whole files, architecture docs, or chat history into every run |

Example questions an agent can ask:

```text
definition of HttpClientBuilder
references to Future
callers of parseConfig
tests for CacheManager
docs about deployment runbooks
```

Those source-shaped questions are where Workspace Knowledge has the most leverage: the agent is not guessing from the current prompt, it is navigating the workspace.

## What Workspace Knowledge connects

Workspace Knowledge combines the context engineers already depend on, then makes it usable by agents.

| Context | Why it matters |
|---------|----------------|
| **Project source** | Agents can inspect the code that implements the system instead of relying on summaries |
| **Docs and runbooks** | Architecture decisions, setup notes, and operating procedures stay available during execution |
| **Code navigation** | Symbol-aware queries help agents follow definitions, callers, references, tests, and related files |
| **Valdr records** | Tasks, reviews, and operational state can become searchable context for future work |
| **Agent Memory Notebooks** | Agents can save practical discoveries, project conventions, and review preferences for the next session |

This is closer to persistent engineering context than a generic knowledge base. It gives orchestrated agents the awareness they need to work across real projects, not just isolated prompts.

## Agent Memory Notebooks

Agent Memory Notebooks make Workspace Knowledge compound over time.

A reviewer can save a project-specific review rule. An executor can remember a migration gotcha. An orchestrator can keep launch notes attached to the project. The next session can retrieve that context without searching old chat transcripts or asking you to explain it again.

Use Agent Memory Notebooks for:

- Project conventions that are not formalized yet
- Review preferences that should survive between sessions
- Investigation findings that future agents should not rediscover
- Temporary operational context that is useful but lower-confidence than official docs

The notebook framing matters: memory is scoped, searchable, and durable. It is not magical global recall. It is practical working memory for agents operating inside a project or workspace.

## How it works

The mechanics are intentionally simple from the operator's point of view:

{{% steps %}}

### Attach context

Attach project repos, docs folders, code folders, or workspace-level references.

### Index what matters

Valdr prepares attached context for search and code navigation so agents can retrieve targeted evidence instead of loading everything into the prompt.

### Ask source-aware questions

Agents can search broadly or use code-map-style questions for definitions, callers, references, tests, docs, and related files.

### Save what should survive

Agents can append notes to Agent Memory Notebooks when they discover something future sessions should know.

{{% /steps %}}

Trusted project documentation ranks above temporary notes and lower-confidence memory, so agents prioritize canonical project context during retrieval. Project-scoped sources stay tied to project repository roots, while global knowledge is reserved for shared workspace context.

## Pairing with Agent Sessions

Workspace Knowledge becomes more powerful when paired with Sovereign Agent Sessions. Before launching or re-engaging an agent, Valdr can give it task state, project context, relevant sources, and prior memory. During the run, the agent can search deeper instead of stopping to ask you for another pasted file.

That is the bigger Sovereign story:

- **Workspace Knowledge** gives agents source-aware context.
- **Agent Memory Notebooks** let context survive between runs.
- **Agent Sessions** turn that context into orchestrated execution, review, audit, and follow-up work.

Together, they move Valdr from workflow tracking into an AI engineering operating environment for agents that need to understand and operate across real projects.

## Guardrails

Workspace context is powerful, so Valdr keeps the boundaries explicit:

- Project sources must live inside that project's repository roots.
- Global sources are guarded against broad home, temp, system, or sensitive paths.
- Credential-looking files and sensitive paths are rejected.
- Disabled sources remain attached but are excluded from default retrieval.
- Knowledge status checks show stale and failed source counts.
- Memory is ranked below trusted project documentation unless you deliberately promote the source.

These guardrails keep agents source-aware without turning them into unbounded filesystem crawlers.

## Next steps

- Read the [`pm_knowledge` MCP reference](/valdr/docs/valdr-mcp/knowledge/) for exact actions and parameters.
- Pair this with [Agent Sessions](/valdr/docs/features/agent-sessions/) to launch agents with persistent workspace context.
- Use [Projects](/valdr/docs/ui/projects/) to understand how project roots define scoped knowledge.