TrainAR Docs
Try Free
Skills & Knowledge · Last updated 18 May 2026 · 5 min read

How the AI uses knowledge

The AI doesn't read your documents the way a person does.

The AI doesn't read your documents the way a person does. It works with a two-stage model: a manifest that tells it what exists, and a vector search (via the built-in search_knowledge skill) that finds the relevant passages when the engineer asks a question.

Stage one: the manifest

When a session starts, the AI receives a manifest of all knowledge available to that seat. The manifest lists each document's name, its collection name (if any), and a short auto-generated summary of its content.

The AI reads this manifest before calling search_knowledge. It uses it to answer the question: "Is there something in this knowledge base that's likely to have the answer?"

If the manifest contains "Worcester Bosch Greenstar 30CDi Installation Manual", the AI knows to search there when an engineer asks about a Worcester 30CDi. If the manifest contains only "Manual", the AI has far less signal.

This is why document names and collection names matter. They're not just labels for your own reference — they're the AI's first-pass routing signal.

When the AI decides to search, it calls search_knowledge (a built-in system skill) with the engineer's query. The search works as follows:

  1. The query is embedded using gemini-embedding-001, producing a 768-dim vector representing the semantic meaning of the question.
  2. That vector is compared against all the chunk embeddings in your knowledge base using cosine distance.
  3. The closest-matching chunks are returned — ranked by semantic similarity, not keyword match.
  4. The AI receives the top-K chunks as text, plus any associated metadata (page number, source file URL for images).
  5. The AI synthesises a response, quoting or paraphrasing the relevant content.

The key implication: the AI finds relevant content even when the exact words don't match. An engineer asking "what's the ignition sequence for the burner?" will surface chunks containing "burner ignition procedure" and "spark electrode sequence" because they're semantically close, not because the engineer used those exact terms.

How images and diagrams surface

When you upload an image — wiring schematic, model plate photograph, exploded diagram — the processing pipeline generates a detailed text description of the visual content. That description is what gets indexed and searched.

When the AI retrieves a chunk that came from an image file, the chunk has a source_file_url pointing back to the original image. If a skill's response target is set to display with display_hint: fullscreen, the AI can surface that image URL and render it directly on the glasses screen. The engineer sees the diagram in their eyeline without reaching for their phone.

This means uploading boiler diagrams as images is genuinely useful — not just as reference files, but as content the AI can find and display on demand.

What happens during a session

A typical retrieval sequence:

  1. Engineer: "What's the flue gas temperature limit for this model?"
  2. AI checks the manifest — there's a service manual for the relevant model in the knowledge base.
  3. AI calls search_knowledge with the query.
  4. The vector search returns two or three chunks from the commissioning section of the manual where flue temperature limits are specified.
  5. AI speaks the answer: "According to the service manual, the maximum flue gas temperature is 120 degrees Celsius at the test point. If it's reading higher, check the heat exchanger for scaling."

The engineer heard the answer in seconds without stopping work.

Reviewing what the AI retrieved

After any session, the session detail page in the Dashboard shows which skills were called and what they returned. For search_knowledge calls, you can see the exact chunks retrieved — the text passages the AI used to formulate its answer.

This is the primary diagnostic tool when the AI isn't finding the right content.

When the AI isn't finding the right content

Problem: the AI says it doesn't have information, but you've uploaded a document that covers it.

  • Check the document's status is Ready. If it's Queued or Processing, the content isn't yet indexed.
  • Check the document name. If it's generic ("Manual"), rename to something specific. The manifest rebuilds at session start, so renaming takes effect immediately.
  • Check the collection name. If the document is in a collection called "Batch 2 Uploads", rename to something descriptive.

Problem: AI is finding content but it's the wrong section.

Usually means relevant content is spread across pages that chunked badly. Try splitting into smaller, focused files — one per topic or product range. Smaller, focused documents chunk more cleanly.

Problem: AI keeps choosing the wrong document when you have several covering similar topics.

Make names and descriptions more specific. If you have installation manuals for Worcester 24i, 28i, and 32i all under one "Worcester Manuals" collection, the AI can't easily distinguish for a 28i-specific question. Separate them with the model number in each document's name.

Problem: AI finds the right document but gives a partial answer.

The relevant content may be split across two chunks. The chunker uses a 50-token overlap which preserves continuity for most documents, but if a critical procedure spans a large PDF page boundary it may be split. Reformat the source so the complete procedure fits within a single section, or add a summary statement at the end of each section the AI can retrieve independently.

Content scope

The AI only searches your tenant's knowledge. It never accesses another tenant's documents. Knowledge scoped to specific roles or seats is only searched for sessions where that role or seat is active. Platform knowledge (from bundles like Parts Arena) is indexed separately and searched by the pa_* skills, not by search_knowledge directly.

Where to next