Skip to content

chat-history.md

Latest commit

 

History

History
465 lines (294 loc) · 9.04 KB

chat-history.md

File metadata and controls

465 lines (294 loc) · 9.04 KB
title Chat History

Chat History

SMG supports multiple storage backends for persisting conversation history, responses, and feedback data for analytics, debugging, and compliance.

Overview

:material-database: Multiple Backends

Choose from in-memory, PostgreSQL, Redis, or Oracle based on your requirements.

:material-message-text: Conversation Tracking

Store complete conversation history including messages, tool calls, and reasoning.

:material-thumb-up: Feedback Collection

Collect user feedback on responses for quality monitoring and fine-tuning.

:material-tune: Configurable Retention

Control data retention with TTL settings for compliance and storage management.

Backend Comparison

Backend Use Case Persistence Scalability
memory Development, testing Process lifetime Single instance
none Stateless deployments None N/A
postgres Production, self-hosted Durable High
redis Caching, ephemeral storage Configurable TTL High
oracle Enterprise, OCI deployments Durable High

Configuration

Backend Selection

smg --history-backend <backend> [backend-specific options]
Option Default Description
--history-backend memory Storage backend: memory, none, oracle, postgres, redis

Memory Backend

The default in-process storage. Suitable for development and testing.

smg --history-backend memory

:material-check-circle: Advantages

  • Zero configuration
  • Fast access
  • No external dependencies

:material-close-circle: Limitations

  • Data lost on restart
  • Not shared across instances
  • Memory grows with conversations

None Backend

Disables history storage entirely. Use for stateless deployments where persistence isn't needed.

smg --history-backend none

Use when: Privacy requirements prohibit storing conversations, or external systems handle logging.

PostgreSQL Backend

Production-ready storage with PostgreSQL.

Configuration Options

Option Default Description
--postgres-db-url - PostgreSQL connection URL
--postgres-pool-max-size 16 Maximum connection pool size

Connection URL Format

postgres://[user[:password]@][host][:port][/database][?param=value]

Examples

Basic Connection

smg --history-backend postgres \
  --postgres-db-url "postgres://user:password@localhost:5432/smg"

With SSL

smg --history-backend postgres \
  --postgres-db-url "postgres://user:password@db.example.com:5432/smg?sslmode=require"

SSL Modes

Mode Description
disable No SSL
allow Try non-SSL first, then SSL
prefer Try SSL first, then non-SSL (default)
require Require SSL, skip verification
verify-ca Require SSL, verify CA
verify-full Require SSL, verify CA and hostname

Redis Backend

High-performance caching with optional persistence and TTL-based retention.

Configuration Options

Option Default Description
--redis-url - Redis connection URL
--redis-pool-max-size 16 Maximum connection pool size
--redis-retention-days 30 Data retention in days (-1 for persistent)

Connection URL Format

redis://[:password@]host[:port][/db]
rediss://[:password@]host[:port][/db]  # TLS

Examples

Basic Connection

smg --history-backend redis \
  --redis-url "redis://localhost:6379"

With TLS and Auth

smg --history-backend redis \
  --redis-url "rediss://:password@redis.example.com:6379"

Persistent Storage

smg --history-backend redis \
  --redis-url "redis://localhost:6379" \
  --redis-retention-days -1

Oracle Backend

Enterprise-grade storage using Oracle Autonomous Database.

Configuration Options

Option Environment Variable Default Description
--oracle-wallet-path ATP_WALLET_PATH - Path to ATP wallet directory
--oracle-tns-alias ATP_TNS_ALIAS - TNS alias from tnsnames.ora
--oracle-dsn ATP_DSN - Direct connection descriptor
--oracle-user ATP_USER - Database username
--oracle-password ATP_PASSWORD - Database password
--oracle-external-auth ATP_EXTERNAL_AUTH false Use external (OS) authentication instead of username/password
--oracle-pool-min ATP_POOL_MIN 1 Minimum connection pool size
--oracle-pool-max ATP_POOL_MAX 16 Maximum connection pool size
--oracle-pool-timeout-secs ATP_POOL_TIMEOUT_SECS 30 Connection timeout in seconds

Examples

Using ATP Wallet

smg --history-backend oracle \
  --oracle-wallet-path /path/to/wallet \
  --oracle-tns-alias mydb_high \
  --oracle-user admin \
  --oracle-password "$ORACLE_PASSWORD"

Using Direct DSN

smg --history-backend oracle \
  --oracle-dsn "(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=db.example.com)(PORT=1521))(CONNECT_DATA=(SERVICE_NAME=myservice)))" \
  --oracle-user admin \
  --oracle-password "$ORACLE_PASSWORD"

What Gets Stored

Conversations

Container for a sequence of interactions:

  • Conversation ID
  • Creation timestamp
  • Metadata (model, user, session info)

Conversation Items

Individual items within a conversation:

Type Description
Messages User and assistant messages with content
Reasoning Model reasoning/thinking steps
Tool Calls Tool invocations and results
MCP Calls MCP server interactions
Function Calls Function calling results

Responses

Complete response records including:

  • Input (original request)
  • Output (model response)
  • Tool calls executed
  • Model information
  • Timestamps and metadata
  • Token usage

Feedback

User feedback on responses for quality tracking:

  • Rating (positive/negative)
  • Comments
  • Timestamp
  • Response reference

Recommended Configurations

:material-laptop: Development

In-memory for fast iteration.

smg --history-backend memory

:material-server-network: Production (Self-Hosted)

PostgreSQL for durable storage.

smg --history-backend postgres \
  --postgres-db-url "postgres://smg:$DB_PASSWORD@postgres:5432/smg?sslmode=require" \
  --postgres-pool-max-size 32

:material-office-building: Enterprise (OCI)

Oracle for enterprise deployments.

smg --history-backend oracle \
  --oracle-wallet-path /etc/smg/wallet \
  --oracle-tns-alias smg_high \
  --oracle-user smg_app \
  --oracle-password "$ATP_PASSWORD" \
  --oracle-pool-max 32

:material-lightning-bolt: Caching Layer

Redis for high-performance ephemeral storage.

smg --history-backend redis \
  --redis-url "rediss://:$REDIS_PASSWORD@redis.example.com:6379" \
  --redis-retention-days 7 \
  --redis-pool-max-size 64

Troubleshooting

Symptom Cause Solution
Connection timeouts Slow network Increase pool timeout
Pool exhaustion High concurrency Increase pool size
Data not persisting Wrong backend Verify --history-backend setting
Redis data expiring TTL too short Increase --redis-retention-days

Pool Configuration

# PostgreSQL
--postgres-db-url "postgres://...?connect_timeout=30"
--postgres-pool-max-size 64

# Oracle
--oracle-pool-timeout-secs 60
--oracle-pool-max 64

# Redis
--redis-pool-max-size 64

What's Next?

:material-shield-lock: Authentication

Secure access to your SMG deployment.

Authentication →

:material-chart-box: Metrics Reference

Monitor storage backend performance.

Metrics Reference →

:material-shield-check: High Availability

Deploy SMG in a highly available configuration.

High Availability →