@agentskit/rag

Plug-and-play retrieval-augmented generation: chunk documents, embed them, and retrieve the right context at query time.

Tags: ai · agents · llm · agentskit · rag · retrieval · vector-search · embeddings · ai-agents · semantic-search · knowledge-base

Verified proof

• Package metadata and tests live under packages/rag/.
• Package guide: https://www.agentskit.io/docs/reference/packages/rag
• Stability map: docs/STABILITY.md

How this fits the ecosystem

@agentskit/rag is the retrieval layer: load documents, chunk them, embed them, rerank results, and feed precise context back to agents.

• AgentsKit: compose it with the other packages in this repo to build agents from small, swappable parts.
• Registry: look for ready agents and templates that already use this layer at registry.agentskit.io.
• Playbook: learn the production patterns behind this layer at playbook.agentskit.io.

Docs: package guide · agent handoff

Why rag

• Your data, your agent — no fine-tuning required; ingest plain text and query with natural language
• Composable stack — uses any EmbedFn and any VectorMemory from @agentskit/adapters and @agentskit/memory; swap either layer without touching RAG logic
• Retriever-ready — createRAG() returns a Retriever you pass to @agentskit/runtime or useChat so context is injected automatically
• Tune chunking without a PhD — chunkSize, chunkOverlap, or a custom split function — three knobs that cover 95% of use cases

Install

npm install @agentskit/rag @agentskit/memory @agentskit/adapters

The file-backed example also needs the optional vectra peer. Add vectra to the install command when using fileVectorMemory; the runtime integration example additionally needs @agentskit/runtime.

Quick example

import { createRAG } from '@agentskit/rag'
import { openaiEmbedder } from '@agentskit/adapters'
import { fileVectorMemory } from '@agentskit/memory'

const rag = createRAG({
  embed: openaiEmbedder({ apiKey: process.env.OPENAI_API_KEY! }),
  store: fileVectorMemory({ path: './vectors' }),
})

await rag.ingest([
  { id: 'doc-1', content: 'AgentsKit is a JavaScript agent toolkit...' },
])

const docs = await rag.search('How does AgentsKit work?', { topK: 5 })
console.log(docs)

With runtime (retriever)

Pass the RAG instance as retriever so the runtime injects retrieved context into the task:

import { createRuntime } from '@agentskit/runtime'
import { openai } from '@agentskit/adapters'

const runtime = createRuntime({
  adapter: openai({ apiKey: process.env.OPENAI_API_KEY!, model: 'gpt-4o' }),
  retriever: rag,
})

const result = await runtime.run('Explain the AgentsKit architecture based on ingested docs')
console.log(result.content)

You can also call rag.retrieve({ query, messages }) to satisfy the core Retriever contract (for example from a custom controller).

Features

• createRAG({ embed, store }) — single entry point for ingest + retrieve.
• rag.ingest(docs) — chunk, embed, and store documents.
• rag.search(query, { topK }) — semantic similarity search.
• rag.retrieve({ query, messages }) — Retriever contract v1 for runtime/controller injection.
• Configurable chunking: chunkSize, chunkOverlap, custom split.
• Works with any EmbedFn and any VectorMemory.
• Rerankers: createRerankedRetriever (Voyage, Jina, custom RerankFn, BM25 default), createHybridRetriever (vector + BM25 blend), standalone bm25Score. Recipe.
• Document loaders: loadUrl, loadGitHubFile, loadGitHubTree, loadNotionPage, loadConfluencePage, loadGoogleDriveFile, loadPdf, loadS3, loadGcs, loadDropbox, and loadOneDrive. Recipe.
• Loader resilience: HTTP/network and response-body read/parse failures surface as RagError (AK_RAG_LOAD_FAILED). Every remote request and body read has a finite timeout and byte limit by default; both are configurable through timeoutMs and maxResponseBytes. timeoutMs defaults to 15 seconds and accepts positive safe integers up to 2,147,483,647ms. Timeouts and optional signal aborts cancel fetches and HTTP body streams when supported. Caller aborts are never swallowed as a per-object skip; timed-out or other individual non-abort failures may be skipped where tree/list partial-success semantics allow it. S3 list/get calls receive the SDK abort signal, and async-iterable object bodies receive return() on cancellation; custom iterators that ignore it may continue in the background. Transform-only S3 bodies may also continue if their transform ignores cancellation. Tree/list loaders may return partial success when at least one eligible download succeeded; if every attempted eligible download failed, they throw. Missing/invalid S3 object bodies count as failed downloads. Pagination that reports more data without a new cursor/token throws (no silent truncation). loadNotionPage follows Notion has_more / next_cursor with start_cursor until complete (preserving block order; incomplete or repeated cursors throw). loadUrl requires an HTTPS origin in allowedOrigins; it does not follow redirects. Non-positive / non-finite maxFiles yields [].
• Score contracts: scoreless search/rerank results keep order. When any score is present, every result must have a finite numeric score and is sorted descending — mixed or non-finite scores throw (never fabricate -Infinity). Malformed Voyage/Jina/custom reranker output throws AK_RAG_RERANK_FAILED. Optional signal on voyageReranker / jinaReranker is forwarded to fetch; request/body aborts remain AK_RAG_RERANK_FAILED. bm25Score sanitizes invalid k1/b to documented defaults and always emits finite scores. Hybrid relative weights are normalized to a finite pair that sums to 1 (both zero → 0.5/0.5).
• Chunk/config safety: invalid chunkSize / chunkOverlap / topK values are sanitized so chunking always terminates and search never sends non-finite limits to the store.
• Ingestion behavior: rag.ingest embeds chunks serially and sends one vector-store batch per call. For large corpora, batch documents in the caller and persist progress between calls; the package does not silently add concurrency or an unbounded background queue.

Markdown notes (@agentskit/rag/markdown)

Pure, synchronous helpers for knowledge-base style Markdown (YAML frontmatter, [[wikilinks]], heading sections, GitHub tables). The subpath is separate so the root entry and its size budget stay free of the yaml parser.

import { parseNote, findSection, parseTable } from '@agentskit/rag/markdown'

const note = parseNote('notes/plan.md', raw)
// { path, title, frontmatter, body, links, frontmatterError? }
const rows = parseTable(findSection(note.body, 'backlog')?.content ?? '')

Also exported: splitFrontmatter, extractWikilinks, stripWikilinks, sections, normalize, plain. Invalid frontmatter never throws; it is reported in frontmatterError.

S3 in Expo and React Native runtimes

Node consumers may install @aws-sdk/client-s3 and let loadS3 resolve it lazily. Browser, Expo/Metro, and React Native bundles keep that peer out of the universal entry; pass the command constructors explicitly when invoking the loader:

import { GetObjectCommand, ListObjectsV2Command, S3Client } from '@aws-sdk/client-s3'
import { loadS3 } from '@agentskit/rag'

await loadS3({
  client: new S3Client({}),
  bucket: 'knowledge',
  commands: { GetObjectCommand, ListObjectsV2Command },
})

Ecosystem

| Package | Role | |---------|------| | @agentskit/core | Retriever, VectorMemory, types | | @agentskit/memory | Vector backends (fileVectorMemory, etc.) | | @agentskit/adapters | openaiEmbedder and other embedders | | @agentskit/runtime | retriever integration for agents | | @agentskit/react | useChat + chat UI with the same core types |

Contributors

License

MIT — see LICENSE.

Docs

Full documentation · GitHub

Maturity and compatibility

• Stability: beta — see docs/STABILITY.md
• Node.js 20+ and TypeScript strict mode
• Published as @agentskit/rag

Contributing

See CONTRIBUTING.md and the monorepo LICENSE.

Partition-bound retrieval

createPartitionedRAG composes createRAG without changing the core Retriever contract or existing createRAG behavior. Bind each instance to a non-empty partition at construction:

import { createPartitionedRAG } from '@agentskit/rag'

const rag = createPartitionedRAG({
  store,
  embed,
  partition: 'team-a',
  topK: 5,
  overfetchFactor: 4,
  onDiagnostics: diagnostics => console.warn(diagnostics),
})
await rag.ingest([{ id: 'guide', content: 'Team A guide' }])
const hits = await rag.retrieve({ query: 'guide' })

Ingest overrides the reserved _akPartition metadata field and namespaces chunk IDs with a JSON tuple, so identical document IDs in different partitions do not overwrite or delete each other's chunks. Document metadata, including documentId, remains available. Returned chunk IDs are opaque namespaced IDs. Every search forwards a core VectorFilter equality predicate and verifies partition metadata locally, rejecting foreign or missing metadata even when a store ignores filters. The wrapper makes one store search, requests at most topK * overfetchFactor candidates, examines at most that many, and returns at most topK matches. The factor is an integer from 1 to 16 (default 4); unsafe candidate limits throw. Per-call search limits and thresholds still work.

The required onDiagnostics callback runs for every successful store search, including empty results, with partition, requestedTopK, candidateLimit, examined, rejected, returned, and recall: 'potentially-reduced'. This is conservative: bounded over-fetch can miss matching chunks, and a store can internally filter a bounded global candidate pool without revealing exclusions (as fileVectorMemory does). Short results never justify returning another partition's chunks. Callback exceptions reject the search.

Stores must faithfully preserve chunk metadata and IDs. Missing metadata fails closed, but fabricated or incorrectly reassigned partition metadata cannot be detected. This is retrieval isolation, not an authorization boundary against untrusted writers or stores. Use physically separate stores or a backend with trusted partition enforcement when that boundary or exhaustive recall is needed. Backend-internal over-fetch is outside the wrapper's candidate bound.