Chat History¶

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

Overview¶

Conversation Tracking¶

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

Feedback Collection¶

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

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

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¶

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¶

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 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¶

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

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

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?¶

Metrics Reference¶

Monitor storage backend performance.

Metrics Reference →

High Availability¶

Deploy SMG in a highly available configuration.

High Availability →