Knowledge

Per-user managed vector store. Upload documents, sync external sources, and give agents semantic search over user-specific knowledge — all without managing embeddings or pgvector yourself.

Knowledge is scoped to a session. Each user's documents are stored in an isolated collection and never mix across sessions. Chunking uses 512-token windows with 50-token overlap, embedded with text-embedding-3-small and indexed with pgvector HNSW.

Uploading documents

Upload one or more files to a named collection. Theazo chunks, embeds, and indexes them automatically. Supported formats: PDF, TXT, MD, DOCX, HTML, CSV.

upload.ts

import { Theazo } from 'theazo'
import { readFile } from 'fs/promises'

const theazo = new Theazo({ apiKey: 'th_live_...' })
const session = await theazo.sessions.forUser('user_123')

// Upload from Buffer — resolves once files are indexed
const pdfBuffer = await readFile('./company-docs.pdf')

await session.knowledge.upload({
  files: [
    { filename: 'company-docs.pdf', content: pdfBuffer, mimeType: 'application/pdf' },
    { filename: 'faq.md', content: Buffer.from(faqMarkdown), mimeType: 'text/markdown' },
  ],
  collection: 'company-knowledge',
})

Upload options

This table is generated from the @theazo/contracts schema — it can't drift from the SDK.

Field	Type	Required	Description
`userId`	`string`	yes	End user the knowledge belongs to.
`collection`	`string`	—	Collection to add the files to. Default: the user default.
`files`	`object[]`	yes	Files to ingest.

Syncing external sources

Connect live data sources. Theazo fetches and re-indexes content on your sync schedule, keeping the vector store fresh without manual uploads.

Notion

await session.knowledge.sync({
  source: {
    type:   'notion',
    config: {
      token:      process.env.NOTION_TOKEN,
      databaseId: 'abc123def456',
    },
  },
  collection: 'user-notes',
  schedule:   '0 */6 * * *',   // re-sync every 6 hours
})

Web pages / sitemaps

await session.knowledge.sync({
  source: {
    type:   'url',
    config: {
      urls:       ['https://docs.acme.com/sitemap.xml'],
      recursive:  true,
      maxDepth:   3,
    },
  },
  collection: 'acme-docs',
  schedule:   '0 2 * * *',   // re-sync nightly at 2am
})

Managing syncs

// List all sources for a session
const srcs = await session.knowledge.sources()

// Delete a source and its indexed data
await session.knowledge.deleteSource('ksync_abc123')

Sync options

This table is generated from the @theazo/contracts schema — it can't drift from the SDK.

Field	Type	Required	Description
`userId`	`string`	yes	End user the knowledge belongs to.
`source`	`object`	yes	Where to sync from.
`collection`	`string`	—	—
`syncSchedule`	`string`	—	Cron/duration to re-sync on; omit for a one-off sync.

Querying knowledge

Run a semantic search against a collection. Returns the top-K most relevant chunks with scores and source metadata. Pass threshold to drop weak matches below a minimum cosine similarity (0–1; default 0 keeps all top-K).

query.ts

const results = await session.knowledge.query(
  'What is our refund policy for enterprise customers?',
  { collection: 'company-knowledge', topK: 5, threshold: 0.7 }
)

for (const result of results) {
  console.log(result.content)   // chunk text
  console.log(result.score)     // 0.0–1.0 cosine similarity
  console.log(result.source)    // 'company-docs.pdf' — source name
  console.log(result.chunk)     // 12 — chunk index within the source
}

query-response.json

// Result shape (KnowledgeResult[]):
// [
//   {
//     content:  'Enterprise refunds are processed within 5 business days...',
//     score:    0.91,
//     source:   'company-docs.pdf',
//     chunk:    12,
//   },
//   ...
// ]

Query options

This table is generated from the @theazo/contracts schema — it can't drift from the SDK.

Field	Type	Required	Description
`userId`	`string`	yes	End user whose knowledge is searched.
`query`	`string`	yes	Natural-language query.
`collection`	`string`	—	Restrict to a collection.
`topK`	`integer`	—	Max results to return. Default 5.
`threshold`	`number`	—	Min cosine similarity (0-1); results below are dropped. Default 0.

Collection stats

const stats = await session.knowledge.stats()

console.log(stats.collections)   // 3
console.log(stats.totalChunks)   // 8432
console.log(stats.totalTokens)   // 4321000
console.log(stats.storageGB)     // 0.42

stats-response.json

// Response shape (KnowledgeStats):
// {
//   collections: 3,
//   totalChunks: 8432,
//   totalTokens: 4321000,
//   storageGB:   0.42,
// }

Agents with knowledge

Enable knowledge access when creating an agent. The agent can then search the session's knowledge collections using the built-in search_knowledge tool.

agent-with-knowledge.ts

// First, make sure knowledge is indexed
await session.knowledge.upload({
  files: [{ filename: 'handbook.pdf', content: handbookBuffer, mimeType: 'application/pdf' }],
  collection: 'company-knowledge',
})

// Create an agent with knowledge access
const agent = await session.agents.create({
  knowledge: true,   // enables the search_knowledge tool automatically
  // Or pass a collection name to restrict the agent to one collection:
  // knowledge: 'company-knowledge',
})

The agent uses search_knowledge automatically — you do not need to configure it as a tool explicitly. It searches across all of the user's collections by default, or only a single collection when you pass its name to knowledge.

Chunking and embedding details

Chunk size512 tokens per chunk

Overlap50 tokens between adjacent chunks to preserve context across boundaries

Embedding modelOpenAI text-embedding-3-small (1536 dimensions)

Index typepgvector HNSW (not IVFFlat) — better recall at query time

Distance metricCosine similarity. Scores range 0.0–1.0, higher is more relevant.

API reference

session.knowledge.upload({ files, collection? })Promise<void>Upload and index documents. Resolves once files are indexed.

session.knowledge.sync({ source, collection?, schedule? })Promise<void>Connect a live source (notion, google_drive, confluence, github, url) with automatic re-indexing.

session.knowledge.query(q, { collection?, topK?, threshold? })Promise<KnowledgeResult[]>Semantic search. Returns top-K chunks by cosine similarity; threshold drops matches below a minimum score.

session.knowledge.stats()Promise<KnowledgeStats>Aggregate stats: collection count, total chunks, total tokens, storage in GB.

session.knowledge.deleteCollection(name)Promise<void>Delete a collection and all its chunks.

session.knowledge.sources()Promise<KnowledgeSourceData[]>List all knowledge sources for the user.

session.knowledge.deleteSource(id)Promise<void>Delete a source and remove all its indexed chunks.