Storage 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

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

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

GET STARTED

CONCEPTS

STARTING AN AGENT PROJECT

READY TO USE SNIPPETS

DEPLOYMENT

FURTHER READINGS

Overview

Sessions Table Schema

User Memory Table Schema

Knowledge Table Schema

Accessing Stored Data

Via Memory Class

Direct Storage Access

​Overview

​Sessions Table Schema

​User Memory Table Schema

​Knowledge Table Schema

​Accessing Stored Data

​Via Memory Class

​Direct Storage Access

Overview

Sessions Table Schema

User Memory Table Schema

Knowledge Table Schema

Accessing Stored Data

Via Memory Class

Direct Storage Access