Knowledge (RAG)

Knowledge lets you upload documents that your agent can search during conversations. Flapjack chunks documents, generates embeddings, and uses pgvector for semantic similarity search. This is retrieval-augmented generation (RAG).

How It Works

Upload document → Chunk into segments → Generate embeddings → Store in pgvector
                                                                      ↓
User asks question → Embed query → Similarity search → Inject top results → Agent responds

1. You upload a document (PDF, text, markdown, etc.)
2. Flapjack splits it into chunks
3. Each chunk is embedded using OpenAI embeddings (1536 dimensions)
4. At query time, the user's message is embedded and matched against chunks
5. Top matching chunks are injected into the agent's context
6. The agent uses the retrieved content to answer

Knowledge Document Fields

Field	Type	Description
id	string	Unique identifier
title	string	Document title
source_ref	string	Original filename or URL
chunk_count	number	Number of chunks created
created_at	string	ISO 8601 timestamp

TypeScript Type

// SDK type (returned by listDocuments and uploadDocument)
type KnowledgeDoc = {
  id: string;
  title: string;
  source_ref: string;
  chunk_count: number;
  created_at: string;
};

Note: The upload API endpoint returns a minimal shape ({ id, title, chunks }), but the SDK's uploadDocument method is typed as Promise<KnowledgeDoc>. The list endpoint returns the full KnowledgeDoc shape.

Uploading Documents

Via SDK

const file = new Blob(['Your document content here...'], { type: 'text/plain' });
const doc = await client.uploadDocument('agent-id', file, 'Product FAQ');
console.log(`Uploaded: ${doc.title}`);

📋 Copy as prompt

Upload a document to my Flapjack agent's knowledge base using client.uploadDocument(agentId, file, title). Use a text file with my product FAQ content.

Via API

curl -X POST https://api.flapjack.dev/api/knowledge/upload \
  -H "Authorization: Bearer fj_live_..." \
  -F "file=@product-faq.pdf" \
  -F "title=Product FAQ" \
  -F "scopeType=agent" \
  -F "scopeId=agent-id"

Listing Documents

const docs = await client.listDocuments('agent-id');
docs.forEach(doc => {
  console.log(`${doc.title} — ${doc.chunk_count} chunks`);
});

Deleting Documents

await client.deleteDocument('doc-id');

Scoping

Knowledge documents can be scoped to:

Scope	Description
org	Available to all agents in the organization
agent	Available only to a specific agent
thread	Available only within a specific thread

Best Practices

• Keep documents focused — smaller, topic-specific documents retrieve better than large general ones
• Use descriptive titles — the title helps with organization but doesn't affect retrieval
• Check chunk count — very large documents produce many chunks; consider splitting them
• Test retrieval — ask your agent questions and verify it finds the right content

Next Steps

• Memory — persistent recall across conversations (different from RAG)
• SDK: Client — uploadDocument, listDocuments, deleteDocument methods
• API: Knowledge — endpoint reference