# FileArtifactStore vs InMemoryArtifactStore in aisuite: Storage Backend Comparison

> Compare FileArtifactStore and InMemoryArtifactStore in aisuite. Learn how disk persistence differs from in RAM speed for your storage needs.

- Repository: [Andrew Ng/aisuite](https://github.com/andrewyng/aisuite)
- Tags: comparison
- Published: 2026-07-27

---

**FileArtifactStore persists artifacts to disk for durability while InMemoryArtifactStore keeps them in RAM for speed, both implementing the same ArtifactStore protocol in aisuite.**

The aisuite library provides two concrete implementations of the `ArtifactStore` protocol for managing binary trace artifacts. Understanding the trade-offs between these storage backends is essential for choosing the right approach for testing versus production tracing scenarios.

## Core Architecture and Protocol

Both stores implement the identical `ArtifactStore` protocol defined in [`aisuite/agents/artifact_store.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/agents/artifact_store.py), exposing `put`, `get`, and `delete` methods for binary data management. They share three core helper functions:

- **`_to_bytes`** (lines 92‑95) – Normalizes `bytes` or `str` payloads to `bytes`
- **`_artifact_metadata`** (lines 98‑106) – Computes SHA‑256 hashes and merges user metadata
- **`_artifact_id`** (lines 82‑89) – Extracts raw IDs from `ArtifactRef` objects or URI strings

The **`ArtifactRef`** dataclass (lines 14‑31) serves as the reference handle for both implementations, differing only in the `uri` field to indicate the backing medium.

## InMemoryArtifactStore: Volatile High-Speed Storage

**InMemoryArtifactStore** maintains artifacts in a Python `dict` stored in RAM for the lifetime of the process. According to the source code, this implementation provides the fastest possible access with O(1) dictionary operations for `put` and `get` calls.

Key characteristics include:

- **URI Scheme**: Generates `memory://<id>` references (line 84)
- **Persistence**: Volatile — all artifacts disappear when the process exits or the store is garbage collected
- **Metadata Storage**: Stored directly in the in-memory `Artifact` object without external files
- **Deletion**: Removes entries using `pop` on the internal dictionary
- **Limitations**: Constrained by available system RAM; unsuitable for large binary payloads or high-volume artifact generation

This backend is ideal for unit tests, short-lived debugging sessions, or scenarios where artifacts are small and temporary.

## FileArtifactStore: Durable File-System Persistence

**FileArtifactStore** writes each artifact to a dedicated directory under a configurable root path on the local filesystem. This implementation prioritizes durability over speed, ensuring artifacts survive process restarts and can be inspected later via external tools.

Key characteristics include:

- **URI Scheme**: Generates `artifact://<id>` references (line 130)
- **Storage Layout**: Creates `<root>/<artifact_id>/` directories containing `data` and [`metadata.json`](https://github.com/andrewyng/aisuite/blob/main/metadata.json) files
- **Metadata Handling**: Writes structured metadata to [`metadata.json`](https://github.com/andrewyng/aisuite/blob/main/metadata.json) alongside the binary data (lines 36‑44)
- **Deletion Semantics**: Removes both the `data` file and [`metadata.json`](https://github.com/andrewyng/aisuite/blob/main/metadata.json), then deletes the artifact directory (lines 66‑78)
- **Scalability**: Limited only by available disk space; suitable for large payloads and long-running production traces

Use this backend for production tracing, debugging sessions requiring post-mortem analysis, or when integrating with the aisuite UI viewer.

## Performance and Scalability Trade-offs

When selecting between these backends, consider the following operational differences:

- **Speed**: **InMemoryArtifactStore** offers superior performance with no I/O overhead, while **FileArtifactStore** incurs latency from file writes, reads, and directory creation operations.
- **Capacity**: **InMemoryArtifactStore** is bound by RAM availability, risking `MemoryError` exceptions with large artifacts. **FileArtifactStore** scales to terabyte-level storage depending on disk configuration.
- **Durability**: Only **FileArtifactStore** provides crash resilience and cross-process artifact sharing through the filesystem.

## Practical Implementation Examples

### Using InMemoryArtifactStore for Testing

The in-memory store is the default choice for unit tests and ephemeral data processing:

```python
import aisuite as ai

store = ai.InMemoryArtifactStore()

# Store a text artifact

ref = store.put(
    "Hello, world!",
    media_type="text/plain",
    metadata={"author": "alice"},
)

# Retrieve it

artifact = store.get(ref)
print(artifact.text())      # → Hello, world!

# Clean-up

store.delete(ref)

```

All operations remain in RAM, and the `ref.uri` will follow the `memory://<id>` format.

### Using FileArtifactStore for Production Tracing

For persistent storage across process restarts, initialize the file-based store with a dedicated directory:

```python
import aisuite as ai
import json
from pathlib import Path

# Store artifacts under a custom directory

store = ai.FileArtifactStore(root=Path("/tmp/aisuite/artifacts"))

# Store a JSON payload

payload = {"result": 42}
ref = store.put(
    json.dumps(payload),
    media_type="application/json",
    metadata={"run_id": "xyz"},
)

# Retrieve later (even after a process restart)

artifact = store.get(ref)
print(artifact.text())      # → {"result": 42}

# Inspect the on-disk layout:

# /tmp/aisuite/artifacts/<artifact_id>/data

# /tmp/aisuite/artifacts/<artifact_id>/metadata.json

# Delete when done

store.delete(ref)

```

Files persist under the configured root directory until explicitly deleted, enabling offline inspection and audit trails.

## Summary

- **FileArtifactStore** writes to the filesystem (`artifact://` URIs) for durable, long-term artifact storage suitable for production environments.
- **InMemoryArtifactStore** uses a Python dictionary (`memory://` URIs) for volatile, high-speed storage ideal for testing and temporary data.
- Both implement the same `ArtifactStore` protocol and share metadata handling logic via `_artifact_metadata` and `_to_bytes` helpers in [`aisuite/agents/artifact_store.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/agents/artifact_store.py).
- File-based storage creates [`metadata.json`](https://github.com/andrewyng/aisuite/blob/main/metadata.json) files alongside binary data, while in-memory storage keeps metadata in object attributes only.
- Choose file storage for debugging and persistence; choose memory storage for speed and test isolation.

## Frequently Asked Questions

### What is the main difference between FileArtifactStore and InMemoryArtifactStore?

**FileArtifactStore** persists artifacts to the local filesystem under a configurable root directory, making data durable across process restarts. **InMemoryArtifactStore** keeps artifacts in a Python dictionary in RAM, providing faster access but losing all data when the process terminates.

### Can I switch between FileArtifactStore and InMemoryArtifactStore without changing my code?

Yes. Both classes implement the identical `ArtifactStore` protocol with the same `put`, `get`, and `delete` method signatures. You can swap implementations by changing the instantiation line while keeping all other artifact handling code unchanged.

### Where does FileArtifactStore save files on disk?

FileArtifactStore creates a subdirectory for each artifact under the `root` path provided at initialization. Each artifact directory contains a `data` file with the binary payload and a [`metadata.json`](https://github.com/andrewyng/aisuite/blob/main/metadata.json) file with SHA‑256 hashes and user metadata, as implemented in lines 36‑44 of [`aisuite/agents/artifact_store.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/agents/artifact_store.py).

### Is InMemoryArtifactStore suitable for production use?

Generally no. While suitable for high-throughput scenarios, **InMemoryArtifactStore** is constrained by available RAM and loses all data on process termination or crashes. For production tracing and debugging workflows requiring post-mortem analysis, **FileArtifactStore** is the recommended backend.