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


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