> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Knowledge Base

> Give agents documents to answer from

Give an Agent a `Knowledge` store and it searches it before answering.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    Agent[🤖 Agent] --> KB[📚 Knowledge]
    KB --> Answer([✅ Answer])

    classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef tool fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef out fill:#10B981,stroke:#7C90A0,color:#fff

    class Agent agent
    class KB tool
    class Answer out
```

## Quick Start

**1. Simple Usage**

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import { Agent, Knowledge } from 'praisonai';

const kb = new Knowledge();
await kb.store('Returns are accepted within 30 days.', { userId: 'u1' });
await kb.add('faqs.pdf', { userId: 'u1' });

const agent = new Agent({
  instructions: 'Answer support questions using the knowledge base.',
  knowledge: kb,
});

await agent.start('What is the return policy?');
```

**2. With Configuration**

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import { Agent, Knowledge, createEmbeddingProvider } from 'praisonai';

const kb = new Knowledge({
  embeddingProvider: createEmbeddingProvider({ model: 'text-embedding-3-small' }),
});

await kb.store('Returns are accepted within 30 days.', { userId: 'u1' });

const agent = new Agent({
  instructions: 'Answer support questions using the knowledge base.',
  knowledge: kb,
  verbose: true,
});
```

***

## Store or Add

Use `store()` for raw text and `add()` for files, directories, or URLs.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
    Input[What are you loading?] --> Text{Raw text?}
    Text -- yes --> Store["kb.store(text, options)"]
    Text -- no  --> File{File / directory / URL?}
    File -- yes --> Add["kb.add(pathOrUrl, options)"]

    classDef q fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef m fill:#8B0000,stroke:#7C90A0,color:#fff

    class Input,Text,File q
    class Store,Add m
```

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import { Knowledge } from 'praisonai';

const kb = new Knowledge();

await kb.store('Our return policy allows returns within 30 days.', { userId: 'u1' });

await kb.add('faqs.pdf', { userId: 'u1' });
await kb.add(['a.pdf', 'b.txt'], { userId: 'u1' });
await kb.add('https://example.com/help', { userId: 'u1' });
```

> [!NOTE]
>
> `kb.add('doc.pdf')` chunks the file internally using the `chunker` block of `KnowledgeStoreConfig`. Use `store()` only for text you already have in memory.

***

## How Search Works

`search()` returns an envelope, not a bare array.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    Q[🔎 query] --> S[Knowledge.search]
    S --> R{{"{ query, results, totalCount }"}}
    R --> Item["results[i].text"]

    classDef q fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef s fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef out fill:#10B981,stroke:#7C90A0,color:#fff

    class Q q
    class S s
    class R,Item out
```

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
const found = await kb.search('return policy', { userId: 'u1', limit: 5 });

console.log(found.query);        // 'return policy'
console.log(found.totalCount);   // number of matches before limit
console.log(found.results[0].text);
```

Each item in `results`:

| Field | Type | Description |
| - | - | - |
| `id` | `string` | Unique identifier |
| `text` | `string` | The stored content |
| `score` | `number` | Relevance score |
| `metadata` | `object` | Stored metadata (always an object) |
| `source` | `string \| null` | Source identifier (e.g. URL) |
| `filename` | `string \| null` | Origin filename, if any |
| `createdAt` | `string \| null` | Creation timestamp |
| `updatedAt` | `string \| null` | Update timestamp |

***

## Configuration Options

`Knowledge` takes a Python-parity config object as its first argument.

> [card] [Knowledge API Reference](https://praison.ai/docs/sdk/reference/typescript/classes/Knowledge.md)
>
> Full `KnowledgeStoreConfig` options

***

## Common Patterns

### Scope by user, agent, or run

Every operation isolates memories by `userId`, `agentId`, and `runId`.

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
await kb.store('Refund promised: $49 by Aug 12.', {
  userId: 'customer_42',
  agentId: 'support_bot_v1',
  runId: 'session_2026_09_03',
});

const scoped = await kb.search('refund promise', {
  userId: 'customer_42',
  agentId: 'support_bot_v1',
});
```

### Search from a tool

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import { Agent, Knowledge, createTool } from 'praisonai';

const kb = new Knowledge();
await kb.store('Important company information...', { userId: 'u1' });

const searchKB = createTool({
  name: 'search_knowledge',
  description: 'Search the knowledge base for relevant information',
  parameters: {
    type: 'object',
    properties: { query: { type: 'string', description: 'Search query' } },
    required: ['query'],
  },
  execute: async ({ query }) => {
    const found = await kb.search(query, { userId: 'u1', limit: 3 });
    return found.results.map(r => r.text).join('\n');
  },
});

const agent = new Agent({
  instructions: 'Use search_knowledge before answering.',
  tools: [searchKB],
});

await agent.start('What do you know about the company?');
```

### Manage stored items

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
const item = kb.get('memory-id');
const all = kb.getAll({ userId: 'u1' });
await kb.update('memory-id', 'Updated content');
kb.delete('memory-id');
kb.deleteAll({ userId: 'u1' });
kb.reset();
```

***

## Best Practices

> [accordion] Always pass a scope
>
> Supply at least one of `userId`, `agentId`, or `runId` on every `store`, `add`, and `search` call so tenants never read each other's data.

> [accordion] Use add() for files, store() for text
>
> `add()` reads and chunks files, directories, and URLs. `store()` takes text you already hold in memory.

> [accordion] Read results\[i].text
>
> `search()` returns `{ query, results, totalCount }`. Read `found.results[i].text`, and page with `limit`.

> [accordion] Enable embeddings for semantic search
>
> Pass `embeddingProvider` in the config to rank results by vector similarity instead of keyword overlap.

***

## Related

> [card] [Knowledge Base CLI](https://praison.ai/docs/js/knowledge-base-cli.md)
>
> CLI knowledge commands

> [card] [Chunking](https://praison.ai/docs/js/chunking.md)
>
> Split documents before storing


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.