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

# File Storage Adapter

> Persist embeddings to local disk

Learn how to use the File Storage Adapter for single-server deployments.

## When to Use

Use `FileStorageAdapter` when:

* Running on a single server
* You have writable disk access
* Embeddings should persist across restarts

## Configuration

```ts title="src/storage/file-adapter.ts" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
import { VectoriaDB, FileStorageAdapter, SerializationUtils } from 'vectoriadb';

const documents = collectToolDocuments();

const toolIndex = new VectoriaDB<ToolDocument>({
  storageAdapter: new FileStorageAdapter({
    cacheDir: './.cache/vectoriadb',
    namespace: 'tool-index',
  }),
  toolsHash: SerializationUtils.createToolsHash(documents),
  version: process.env.npm_package_version,
});

await toolIndex.initialize();

if (toolIndex.size() === 0) {
  await toolIndex.addMany(documents);
  await toolIndex.saveToStorage(); // Persist to disk
}
```

## Options

| Option      | Type   | Default               | Description               |
| ----------- | ------ | --------------------- | ------------------------- |
| `cacheDir`  | string | `./.cache/vectoriadb` | Directory for cache files |
| `namespace` | string | `'default'`           | Namespace for isolation   |
| `fileName`  | string | `'embeddings.json'`   | Cache file name           |

## File Structure

The adapter creates this structure:

```
.cache/vectoriadb/
└── tool-index/              # namespace
    └── embeddings.json      # cache file
```

## Directory Permissions

Ensure the cache directory is writable:

```ts title="src/directory-setup.ts" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
import * as fs from 'fs/promises';

// Create cache directory if it doesn't exist
await fs.mkdir('./.cache/vectoriadb', { recursive: true });

const db = new VectoriaDB({
  storageAdapter: new FileStorageAdapter({
    cacheDir: './.cache/vectoriadb',
  }),
});
```

## Error Handling

```ts title="src/file-error-handling.ts" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
import { StorageError } from 'vectoriadb';

try {
  await db.saveToStorage();
} catch (error) {
  if (error instanceof StorageError) {
    console.error('Failed to save:', error.message);

    // Common issues:
    // - Permission denied
    // - Disk full
    // - Path doesn't exist
  }
}
```

## Security Considerations

The adapter includes path traversal protection:

```ts title="src/security.ts" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
// These are sanitized automatically:
const adapter = new FileStorageAdapter({
  namespace: '../../../etc/passwd', // Sanitized to safe string
});
```

<Warning>
  Never pass untrusted user input directly to the `namespace` option. Always sanitize external input.
</Warning>

## Docker Volumes

When using Docker, mount the cache directory as a volume:

```yaml title="docker-compose.yml" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
services:
  app:
    volumes:
      - vectoria-cache:/app/.cache/vectoriadb

volumes:
  vectoria-cache:
```

## Related

<CardGroup cols={3}>
  <Card title="Storage Overview" icon="floppy-disk" href="/vectoriadb/guides/storage/overview">
    Storage fundamentals
  </Card>

  <Card title="Redis Adapter" icon="database" href="/vectoriadb/guides/storage/redis-adapter">
    Multi-pod storage
  </Card>

  <Card title="Cache Invalidation" icon="rotate" href="/vectoriadb/guides/storage/cache-invalidation">
    Cache control
  </Card>
</CardGroup>