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

# Storage Tables

> What data is stored in the session, user memory, and knowledge tables

## Overview

The storage system uses the following tables/collections to persist data:

* **Sessions Table**: Stores conversation history, summaries, runs, and metadata
* **User Memory Table**: Stores user profiles and extracted traits
* **Knowledge Table**: Stores document registry metadata for KnowledgeBase (when `storage` is passed to a KnowledgeBase)

## Sessions Table Schema

Stores all session-related data including messages, runs, and summaries.

| Field          | Type      | Description                                             |
| -------------- | --------- | ------------------------------------------------------- |
| `session_id`   | `string`  | Primary key, unique session identifier                  |
| `session_type` | `string`  | Type: `"agent"`, `"team"`, or `"workflow"`              |
| `agent_id`     | `string`  | Associated agent ID                                     |
| `team_id`      | `string`  | Associated team ID (for team sessions)                  |
| `workflow_id`  | `string`  | Associated workflow ID (for workflow sessions)          |
| `user_id`      | `string`  | User identifier for cross-session tracking              |
| `messages`     | `json`    | Full conversation history (ModelRequest/ModelResponse)  |
| `summary`      | `string`  | Generated session summary (if `summary_memory=True`)    |
| `runs`         | `json`    | Individual run outputs with status, requirements, usage |
| `metadata`     | `json`    | Custom session metadata                                 |
| `usage`        | `json`    | Usage details for the session                           |
| `created_at`   | `integer` | Unix timestamp of creation                              |
| `updated_at`   | `integer` | Unix timestamp of last update                           |

## User Memory Table Schema

Stores user profiles and traits extracted from conversations.

| Field         | Type      | Description                                  |
| ------------- | --------- | -------------------------------------------- |
| `user_id`     | `string`  | Primary key, unique user identifier          |
| `user_memory` | `json`    | Extracted user traits and preferences        |
| `agent_id`    | `string`  | Agent that extracted these traits (optional) |
| `team_id`     | `string`  | Team that extracted these traits (optional)  |
| `created_at`  | `integer` | Unix timestamp of creation                   |
| `updated_at`  | `integer` | Unix timestamp of last update                |

## Knowledge Table Schema

Stores document metadata for KnowledgeBase instances. Created automatically when a `storage` backend is passed to a `KnowledgeBase`. The default table name is `upsonic_knowledge`.

| Field               | Type      | Description                                           |
| ------------------- | --------- | ----------------------------------------------------- |
| `id`                | `string`  | Primary key, document ID (content-based hash)         |
| `name`              | `string`  | Human-readable document name                          |
| `description`       | `string`  | Optional document description                         |
| `metadata`          | `json`    | Full document metadata (file path, loader info, etc.) |
| `type`              | `string`  | File extension (e.g., `pdf`, `md`, `csv`)             |
| `size`              | `integer` | File size in bytes                                    |
| `knowledge_base_id` | `string`  | ID of the parent KnowledgeBase                        |
| `content_hash`      | `string`  | MD5 hash of document content for deduplication        |
| `chunk_count`       | `integer` | Number of chunks created from this document           |
| `source`            | `string`  | Original file path or source identifier               |
| `status`            | `string`  | Processing status (`indexed`, `failed`)               |
| `status_message`    | `string`  | Optional status details (e.g., error message)         |
| `access_count`      | `integer` | Number of times the document has been accessed        |
| `created_at`        | `integer` | Unix timestamp of creation                            |
| `updated_at`        | `integer` | Unix timestamp of last update                         |

## Accessing Stored Data

### Via Memory Class

```python theme={null}
from upsonic.storage.memory import Memory
from upsonic.storage.sqlite import SqliteStorage

storage = SqliteStorage(db_file="data.db")
memory = Memory(storage=storage, session_id="session_001")

# Get current session
session = memory.get_session()
print(session.messages)
print(session.summary)

# List all sessions for a user
sessions = memory.list_sessions(user_id="user_123")
```

### Direct Storage Access

```python theme={null}
from upsonic.storage.sqlite import SqliteStorage

storage = SqliteStorage(db_file="data.db")

# Get session directly
session = storage.get_session(session_id="session_001", deserialize=True)

# Get user memory directly
user_memory = storage.get_user_memory(user_id="user_123", deserialize=True)
print(user_memory.user_memory)  # Dict of traits
```