Integration  ·  AI operations

How to build a knowledge base to vector sync

An assistant confidently quotes a policy that was retired last year. Here is the model behind a vector index that keeps up, the prompts that build it, and what it takes to run in production.

Built with Tray Headless

  1. System Notion
  2. Step Chunk on structure
  3. Step Carry permissions
  4. Step Embed changed only
  5. System Vector store
Also Delete on delete

Permissions travel with the chunk into the index, so retrieval filters before it ranks rather than after.

The short answer

What is a knowledge base to vector sync?

A knowledge base to vector sync has four moving parts: chunking on document structure instead of character count, permissions carried into the index so retrieval filters before it ranks, deletion propagated immediately because a retired document that still answers questions is worse than a missing one, and re-embedding only what changed. Teams usually come unstuck on permissions. An index built without them will happily answer a contractor question using the board deck, and nobody discovers it until it happens.

What matters here

  • Carry permissions into the index. Filtering after retrieval still means the content was retrieved and often still leaks in a summary.
  • Chunk on structure, not character count. A chunk that spans two sections answers questions about neither.
  • Delete on delete, immediately. A retired policy that still answers questions is worse than no answer at all.
  • Re-embed only changed chunks. Full re-embedding is expensive and hides which change actually mattered.
  • Keep the source link on every chunk. An answer nobody can verify is an answer nobody should act on.

Who this is for

You run AI operations or knowledge management. An assistant is answering from company documents, and nobody can say whether those documents are current or who should be able to see them.

How it works in practice

Everything that sits between a document changing and an assistant answering correctly.

  1. 1

    Source documents are watched for change

    Created, edited, moved, permission-changed and deleted, all of which matter.

  2. 2

    Chunking follows the document structure

    Headings and sections, with overlap, so a chunk is about one thing.

  3. 3

    Permissions are captured with the chunk

    Whichever groups could read the source, carried as metadata into the index.

  4. 4

    Only changed chunks are re-embedded

    On a content hash, because re-embedding everything is expensive and uninformative.

  5. 5

    Deletion propagates immediately

    A removed or retired document leaves the index in the same run, not the next nightly.

  6. 6

    Retrieval filters on permission before ranking

    So a chunk somebody may not see is never a candidate at all.

What the sync is made of

Four parts. The second is the difference between a useful assistant and an incident.

Structural chunking

Split on headings and sections with overlap. A fixed character split produces chunks spanning two topics that answer questions about neither.

Permissions in the index

The source ACL carried as chunk metadata, so retrieval filters before ranking instead of after.

Immediate deletion

Removed at source means removed from the index in the same run. A confidently quoted retired policy is worse than no answer.

Delta re-embedding

A content hash per chunk. Re-embedding everything on every run is expensive and tells you nothing about what changed.

The Tray Headless prompts

Paste these into Claude Code or Codex with the Tray Headless plugin installed. Each stage runs on its own. The systems named in them are the worked example rather than a requirement, and every prompt says so.

Once per project, run /tray-workflows:set-workspace to pick the workspace these build in. Point it at a sandbox first.

  1. 1

    First, find where permissions actually live

    This is the part that decides whether the index is safe.

    Headless skills build-workflow tray-patterns 

    Use build-workflow. The systems in play are Notion, Google Drive and
Confluence, or whatever we run in those seats.

For each source I need: how to list documents and detect change, how to
read content, and critically how to read the permissions on a document,
including inherited ones from a parent folder or space.

Permissions are the hard part and the one that decides whether this index
is safe to query. If a source cannot tell us who may read a document,
that source cannot go into a shared index, and I would rather know that
now than after somebody is quoted a document they should never have
seen.
  2. 2

    Chunk on structure, keep the source

    A chunk spanning two sections answers questions about neither.

    Headless skills build-workflow 

    Use build-workflow. Chunk on the document structure rather than a
character count:

  Split on headings, keeping the heading path as metadata so a chunk
  knows where it came from
  Keep tables and code blocks whole, because splitting them destroys them
  Overlap slightly between adjacent chunks so a sentence at a boundary
  is not orphaned
  Cap length, and split a long section at a paragraph rather than
  mid-sentence

Attach to every chunk: source system, document id, heading path, a
deep link, last modified date and author.

The link matters as much as the content. An answer nobody can verify is
an answer nobody should act on, and the link is what turns a claim into
something checkable.
  3. 3

    Carry permissions into the index

    Filtering after retrieval means it was already retrieved.

    Read the effective permissions on every source document, including
inheritance, and store them as chunk metadata: which groups and which
individuals may read it.

Filter on those at query time, before ranking, not after. Retrieving a
chunk and then discarding it still means the content was pulled, and it
frequently still influences a generated summary.

Anything whose permissions cannot be determined does not enter the index.
Not as public, not as restricted, not at all.

Re-check permissions on a schedule as well as on change. A document moved
into a restricted folder does not always emit a change event, and that
silent case is exactly the one that leaks.

    Permission changes are the event most source systems handle worst. Re-checking on a schedule is the belt to that braces.

  4. 4

    Delete on delete, and re-embed only what changed

    A retired policy that still answers questions is worse than no answer.

    Headless skills tray-gotchas 

    Use tray-gotchas, then handle removal and change properly.

Deletion propagates in the same run: deleted, archived, unpublished or
moved out of scope all remove the chunks immediately. An assistant
confidently quoting a policy retired last year is worse than one that
says it does not know.

Hash each chunk's content. Re-embed only chunks whose hash changed. A
typo fix in one paragraph should not re-embed a hundred-page handbook.

Handle these: a document renamed instead of changed, a page moved
between spaces, an attachment updated without the page changing, a source
system rate limiting a large backfill, and a document whose permissions
changed but whose content did not.
  5. 5

    Watch freshness and answerability

    A stale index fails silently and confidently.

    Report: documents indexed by source, chunks added, updated and deleted
per run, embedding spend, and the oldest unrefreshed document per source.

Then the two that actually matter:

  Staleness: documents changed at source more than a day ago and not yet
  reflected. That number should be near zero and it is the one that makes
  an assistant wrong.
  Retrieval quality: how often a query returns nothing, which usually
  means a gap in the corpus rather than a bad question.

Alert if a source stops emitting changes entirely. A sync that silently
stopped looks identical to a knowledge base nobody edited this week.
  6. 6

    Validate it, then hand the sources over

    Because which documents are authoritative is a business decision.

    Run the per-step schema checks and the whole-workflow audit before this
touches production. Test permission filtering deliberately: query as
somebody restricted and confirm the restricted chunks are not merely
hidden but never retrieved.

Then open the same workflow in Tray Build so knowledge management can add
sources, exclude spaces and set refresh cadences in the visual canvas.

What it connects to

Documents live in several places and have to reach one index without losing who may read them.

Notion

Read pages, their content and their effective permissions including inherited ones.

Reads

Google Drive

Read documents and folder-level sharing, which is where most inherited permission surprises come from.

Reads

Confluence

Read spaces and pages with their restrictions, and detect archival as a deletion event.

Reads

Okta

Resolve groups so index permissions and query-time identity use the same source.

Reads

Snowflake

Hold chunk metadata, hashes and sync history, so staleness and re-embedding cost are measurable.

Reads and writes

Slack

Alert when a source stops emitting changes, because a silently stopped sync looks like a quiet week.

Writes

Same build, other stacks

The design does not change if you run something else in one of these seats. The same prompts build it against Google BigQuery, Microsoft Teams, Azure Active Directory, SharePoint, Databricks or Google Chat.

Named systems are the ones most teams run, not the only ones that work. Each is an authentication in your Tray workspace, referenced by name, so the workflow never holds a credential. Where we have a connector page, the name links to it.

Running it in production

This decides what an assistant knows and who it will tell. Both halves are security-relevant.

It lives on the platform, not in a terminal window

Change detection, embedding and deletion run continuously on the same engine, with retries and a per-document history.

Permissions are enforced in the index

Carried as chunk metadata and filtered before ranking. Post-retrieval filtering means the content was already pulled and may already have influenced an answer.

Credentials live in the workspace, never in the repo

Read access across every knowledge source is a broad permission, and one that changes what an assistant can repeat. Each source is an authentication in your workspace, read-only and separately rotatable.

Knowledge management owns the sources

Which spaces are indexed, what is excluded and how often it refreshes open in Tray Build, owned by the people who know what is authoritative.

Staleness is reported, not assumed

Documents changed at source and not yet reflected. That number is the one that makes an assistant confidently wrong.

Questions people ask

Why carry permissions into the index?

Because filtering after retrieval still means the content was retrieved, and it often still influences a generated summary. Filtering before ranking is the only version that actually restricts anything.

Why chunk on structure rather than character count?

Because a fixed split produces chunks that span two sections and answer questions about neither. Splitting on headings keeps a chunk about one thing and lets it carry its own context.

How quickly should deletions propagate?

In the same run. An assistant confidently quoting a policy retired last year is worse than one that says it does not know, and the confidence is what makes it dangerous.

Why re-embed only changed chunks?

Because full re-embedding is expensive and uninformative. A typo fix in one paragraph should not re-embed a hundred-page handbook, and a hash per chunk makes that trivial.

What happens to a document whose permissions cannot be read?

It does not enter the index. Not as public, not as restricted, not at all. A source that cannot say who may read a document cannot safely contribute to a shared index.

Related guides

AI operations

How to expose an internal system as an MCP tool

Scope the tool to a job rather than an API, resolve identity per call, make writes idempotent, and log every invocation. The Headless prompts that build it.

AI operations

How to build human approval for agent actions

Decide what needs approving by blast radius, show the approver what will happen, expire cleanly, and keep the record. The Headless prompts that build it.

AI operations

How to build AI support deflection

Answer only what the knowledge base actually covers, escalate early with the context, and measure resolution rather than deflection. The prompts that build it.

Last reviewed September 2026.