> ## 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 Storage

> Where agent knowledge is persisted, how to change it, and how to recover a corrupt store

Knowledge persists to an absolute, per-project Chroma store so unrelated projects never share one on-disk database.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "Knowledge storage"
        A[🧑 Agent] --> B[📚 Knowledge]
        B --> C{🔧 path set?}
        C -->|No| D[📁 .praisonai/knowledge/chroma]
        C -->|Yes| E[📁 Your path]
        D --> F[(🗃️ Chroma)]
        E --> F
    end

    classDef input fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef process fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef decision fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef output fill:#10B981,stroke:#7C90A0,color:#fff

    class A input
    class B,F process
    class C decision
    class D,E output
```

## Quick Start

**1. Use the default location**

Pass sources and let the store persist under the per-project default.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent

agent = Agent(
    name="Research Assistant",
    knowledge=["docs/"]
)

agent.start("Summarize the docs")
```

Data lands at `<project>/.praisonai/knowledge/chroma`.

**2. Choose your own location**

Set `vector_store.config.path` to store data anywhere you like.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent

agent = Agent(
    name="Research Assistant",
    knowledge={
        "sources": ["docs/"],
        "vector_store": {
            "config": {"path": "/data/my_project/chroma"}
        }
    }
)

agent.start("Summarize the docs")
```

***

## Where Is My Data Stored?

Omit `path` and Knowledge persists to an absolute directory derived from your project root.

| Setting | Location |
| - | - |
| Default (no `path`) | `<project>/.praisonai/knowledge/chroma` |
| Explicit `path` | Exactly the directory you provide |

The default is **absolute** and **per-project**, so two projects — or a test harness that changes directories — never write to the same sqlite file.

> [!NOTE]
>
> Earlier releases defaulted to the cwd-relative string `"knowledge_db"`, which let unrelated projects collide. Upgrade to the release built from PraisonAI PR [#4422](https://github.com/MervinPraison/PraisonAI/pull/4422) for the isolated default.

***

## How to Change It

Point `path` at any directory via the Agent config or a standalone `Knowledge` instance.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Knowledge

kb = Knowledge(config={
    "vector_store": {
        "config": {"path": "/data/shared/chroma"}
    }
})

kb.add("research.pdf")
```

An explicitly configured `path` always wins over the default.

***

## What If the Store Is Corrupt?

A corrupt, locked, or version-mismatched Chroma store now raises a `RuntimeError` instead of crashing the interpreter.

```
RuntimeError: Chroma persist failed at '<path>' (PanicException: <text>).
Pass a fresh directory via knowledge config vector_store.config.path.
```

ChromaDB's rust bindings can raise a `PanicException` (a `BaseException`, not `Exception`) that previously unwound through `Agent.start` and killed Python — on Windows this showed up as a SIGSEGV or hang ([issue #4376](https://github.com/MervinPraison/PraisonAI/issues/4376)). The SDK now catches it and re-raises an actionable Python error, while `KeyboardInterrupt` still propagates so Ctrl-C keeps working.

Directory indexing behaves the same: a backend panic on one file surfaces as `RuntimeError: Knowledge indexing backend crashed on <file>` rather than terminating the process.

**Recovery:** delete the persist directory and re-index, or point `path` at a fresh directory.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import shutil
from praisonaiagents import Agent

shutil.rmtree(".praisonai/knowledge/chroma", ignore_errors=True)

agent = Agent(name="Research Assistant", knowledge=["docs/"])
agent.start("Re-index and answer")
```

***

## Configuration Options

Chroma persistence is controlled by a single option under `vector_store.config`.

| Option | Type | Default | Description |
| - | - | - | - |
| `path` | `str` | `<project>/.praisonai/knowledge/chroma` (absolute, per project) | Directory where the Chroma sqlite store is persisted. Optional — omit to use the per-project default. |

***

## Best Practices

> [accordion] Omit path for local development
>
> Leave `path` unset and rely on the per-project default. Each project keeps its own isolated store with zero configuration.

> [accordion] Set an explicit path for shared or deployed stores
>
> Point `path` at a stable, absolute directory when multiple services must read the same knowledge base, or when deploying where the working directory changes.

> [accordion] Recover instead of retrying on a panic
>
> A `RuntimeError: Chroma persist failed ...` means the store is corrupt or locked. Delete the directory or switch to a fresh `path` — re-running against the same broken store repeats the failure.

> [accordion] Isolate per environment
>
> Use distinct paths for development, test, and production so an experiment never corrupts a shared index.

***

## Related

> [card] [Knowledge](https://praison.ai/docs/features/knowledge.md)
>
> Add documents and query them from an agent

> [card] [Knowledge Backends](https://praison.ai/docs/features/knowledge-backends.md)
>
> Pick and configure a vector store


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