Workspace Knowledge for AI Agents

Sovereign

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.

Agents stop wasting cycles

They retrieve project docs, source context, operational notes, and previous discoveries before they act

Deep dives span projects

Agents can follow definitions, callers, references, tests, docs, and related code across attached sources

Context compounds

Agent Memory Notebooks preserve useful findings so the next session does not rediscover them

Sessions get smarter

Launched agents start with richer context and can keep searching while they work

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.

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.

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:

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:

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.

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 for exact actions and parameters.
Pair this with Agent Sessions to launch agents with persistent workspace context.
Use Projects to understand how project roots define scoped knowledge.

Agent Sessions for Orchestrated AI Workflows