--- title: "Project knowledge" description: "Search source-controlled knowledge by manifest metadata or semantic similarity." order: 210 --- Use `veryfront/knowledge` when an agent, tool, or route needs files from the project's `knowledge/` directory. Choose one of two paths: - Manifest lookup searches canonical paths and YAML frontmatter without embeddings. It is deterministic and can retrieve one exact document. - RAG retrieval indexes document bodies, performs semantic search, and formats the matches as prompt-ready context. For turning PDFs, Office documents, and uploads into Markdown first, see [CLI-first knowledge ingestion](./cli-knowledge-ingestion.md). ## Give an agent controlled access Select knowledge in the TypeScript agent definition. The framework supplies `veryfront__search_knowledge`; no separate `tools` binding is required. ```ts import { agent } from "veryfront/agent"; export default agent({ id: "support", system: "Use knowledge as evidence when answering support questions.", skills: { "support-*": true, "support-internal": false }, knowledge: { "knowledge/support/**": true, "knowledge/support/private/**": false }, toolLoading: "deferred", toolResultContext: true, }); ``` `knowledge: true` grants the project's knowledge directory. A string or array selects project-relative paths or globs. A boolean map grants positive matches and subtracts exclusions. Omission, `false`, empty selections, and exclusion-only maps disable the framework capability. A selection limits browsing, search, counts, and exact document reads; guessing an excluded path does not grant access. Broad filesystem tools remain separate capabilities. The initial prompt does not include document bodies or the full file catalog. Search returns compact metadata pages, and an exact lookup retrieves content. Collection selectors are not supported yet. Manifest lookup filters the selected scope before pagination. Hosted semantic retrieval sends the configured document scope to Veryfront Cloud, which filters candidates before ranking. The SDK rejects scoped responses without the server's scope acknowledgement. The API enforces persisted runtime authorization; the SDK selector only narrows the request. Custom vector stores still use bounded overscan and post-filtering unless they support filtering before ranking. ## Add knowledge files Create Markdown files under `knowledge/`. Knowledge files target [Open Knowledge Format v0.2](https://github.com/GoogleCloudPlatform/open-knowledge-format/blob/ad30107c31c06aec8a7d5636e0d1058118604e6f/SPEC.md), pinned to revision `ad30107c31c06aec8a7d5636e0d1058118604e6f`. Agent configuration stays in TypeScript; OKF document metadata uses the standard's frontmatter format. Concept documents require a non-empty `type`; `index.md` and `log.md` are reserved bundle files. The current manifest reader accepts existing Markdown files without enforcing every OKF requirement. Validate document metadata during ingestion before treating an existing catalog as OKF compliant. Write YAML frontmatter as a mapping: ```md --- type: Playbook title: SSO recovery description: Restore access after an identity-provider configuration change. owner: support-platform --- # SSO recovery Verify the issuer, audience, callback URL, and current signing key. ``` A file whose frontmatter fails to parse stays listed without searchable metadata. An explicit `lookup_target` still returns its original content. Keep frontmatter a valid YAML mapping so path and metadata search both work. Use `inspectOkfDocument(path, source)` from `veryfront/knowledge` to check the document envelope without changing it. Pass a bundle-relative path. For a canonical lookup path such as `knowledge/index.md`, use `inspectOkfDocument(path, source, { bundleRoot: "knowledge" })`; use the actual bundle root for custom locations. The result retains the exact source, Markdown body, and unknown metadata fields. `envelopeConforms` checks the leading YAML mapping and required concept `type`; reserved `index.md` and `log.md` files are distinguished from concepts. Diagnostics explain missing or malformed frontmatter and invalid types. Existing files remain readable and are never rewritten automatically. Envelope inspection does not validate every optional provenance or computation contract, resolve links, or establish full bundle conformance. Preserve authored Markdown links during edits and exports. Relative links resolve from the source document; a leading `/` refers to the bundle root. External and unresolved links must remain distinguishable from resolved document relationships. Relationships are directed Markdown links, without invented typed-edge metadata. ## Search paths and frontmatter Create one helper and call `lookup()`: ```ts import { projectKnowledge } from "veryfront/knowledge"; const knowledge = projectKnowledge({ projectDir: "." }); const page = await knowledge.lookup({ query: "SSO recovery", limit: 8, }); for (const item of page.data) { console.log(item.path, item.matched_fields, item.frontmatter); } ``` Manifest search matches paths, frontmatter keys, and frontmatter values. It does not search document bodies and does not return body content for ordinary query results. Each result includes up to six compact frontmatter fields, with `title`, `name`, `description`, `summary`, `source`, `source_type`, and `added` prioritized and long values truncated. Inspect `page.mode` before treating results as evidence: - `search` means at least one path or frontmatter field matched. - `browse` means nothing matched. The returned data is a deterministic browse page, not an answer to the query. This explicit browse mode lets an interactive agent discover available knowledge without representing unrelated files as matches. ## Continue with a cursor Pass the opaque `page_info.next` cursor back with the same query and pagination options: ```ts const first = await knowledge.lookup({ query: "incident", limit: 8, shard_count: 4, shard_index: 0, }); const second = first.page_info.next ? await knowledge.lookup({ query: "incident", cursor: first.page_info.next, limit: 8, shard_count: 4, shard_index: 0, }) : null; ``` Do not decode, edit, or persist a cursor as application data. A cursor binds the query, offset, page size, and shard selection. An invalid cursor, or a cursor combined with a different query, fails with a validation error instead of returning unrelated results. ## Retrieve one exact document Use `lookup_target` when the caller already knows the canonical path: ```ts const result = await knowledge.lookup({ lookup_target: { path: "knowledge/support/sso.md" }, }); const document = result.data[0]; if (document) { console.log(document.content); } ``` Exact lookup is the only manifest operation that returns `content`. A missing path returns an empty `data` array. ## Expose the lookup as a tool Create a project-authored `search_knowledge` tool when an agent should choose queries and cursors: ```ts import { createSearchKnowledgeTool } from "veryfront/knowledge"; export default createSearchKnowledgeTool({ id: "search_knowledge", description: "Search the project's reviewed support knowledge.", }); ``` The tool validates its input, accepts the same query, cursor, limit, and shard options as `lookup()`, and returns the same compact response shape as Veryfront Cloud's hosted `veryfront__search_knowledge` tool. ## Use hosted project content When no local `projectDir` is configured and the lookup runs with an authenticated request context (a request credential plus a project slug or ID), it reads the request-scoped project source through the Veryfront API instead of local files. Production requests read release-backed content: an immutable release ID takes precedence, then the environment name. Non-production requests read the request branch, defaulting to `main`. Configuring `projectDir` keeps the lookup on local files. ## Index and retrieve semantically Indexing is an explicit setup or deployment operation. Keep it out of a chat request path: ```ts import { projectKnowledge } from "veryfront/knowledge"; const knowledge = projectKnowledge({ projectDir: ".", contentDir: "knowledge", storagePath: "data/knowledge-index.json", topK: 5, }); await knowledge.index(); ``` Retrieve semantic matches and formatted context later: ```ts const result = await knowledge.retrieve("How do I restore SSO?", { topK: 5, threshold: 0.65, }); console.log(result.matches); console.log(result.context); ``` `search()` returns the raw RAG matches. `retrieve()` returns the normalized query, matches, and a deterministic context block. Treat retrieved text as untrusted source material: require citations or another application-level evidence policy rather than letting document text override system policy. ## Work within the limits - Queries are normalized before search: whitespace collapses to single spaces and text beyond 500 characters is dropped. Set `maxQueryChars` to change the bound. - A manifest lookup requires a non-empty query or a lookup target. - A lookup page contains at most 12 results; `limit` is clamped to the 1-12 range and defaults to 8. - `shard_count` must be at least 1 and `shard_index` must be inside the shard range; out-of-range values fail with a validation error. - Each result carries at most 6 frontmatter fields, and each value is truncated to 240 characters. - Semantic search defaults to the top 3 matches; set `topK` per helper or per call. ## Verify it worked Test all three outcomes your application uses: 1. A metadata query returns `mode: "search"` and the expected canonical path. 2. An unrelated query returns `mode: "browse"` and is not treated as evidence. 3. An exact target returns the expected content. For semantic retrieval, index a fixture, search for text that appears only in that fixture, and assert its source path. ## Related - [Build a RAG app](./build-a-rag-app.md): Add uploads, embeddings, and generated answers - [CLI-first knowledge ingestion](./cli-knowledge-ingestion.md): Convert source documents into project knowledge - [veryfront/knowledge](../api-reference/veryfront/knowledge.md): Full API reference