Chat History¶

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

Overview¶

Multiple Backends¶

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

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

✓ Advantages¶

Zero configuration
Fast access
No external dependencies

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

Development¶

In-memory for fast iteration.

smg --history-backend memory

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

Authentication¶

Secure access to your SMG deployment.

Authentication →

Metrics Reference¶

Monitor storage backend performance.

Metrics Reference →

High Availability¶

Deploy SMG in a highly available configuration.

High Availability →