/hindsight-docs

Storage

Hindsight uses PostgreSQL as its primary storage backend, with Oracle AI Database available as an alternative for enterprise deployments.

Why PostgreSQL?

PostgreSQL provides all capabilities required for a semantic memory system in a single database:

Reduced System Dependencies

Building exclusively for PostgreSQL simplifies deployment and operations:

• Single connection string to configure
• Single backup and restore strategy
• Single monitoring target
• ACID transactions across all data types
• Single upgrade path

No Storage Abstraction

Hindsight does not abstract storage behind a generic interface. This is a deliberate trade-off.

We believe PostgreSQL is becoming the standard database API. Its popularity, extension ecosystem, and modularity mean that PostgreSQL-compatible interfaces are appearing everywhere—from serverless offerings to distributed databases. Building for PostgreSQL today means compatibility with a growing ecosystem tomorrow.

Supporting multiple databases would increase flexibility but conflict with our core goals: Hindsight is fully open source and designed to be as simple as possible to run and use. Adding database abstractions introduces complexity in code, testing, documentation, and operations—complexity that we pass on to users.

By building on PostgreSQL, we keep the system simple:

• One set of deployment instructions
• One set of performance characteristics to understand
• One codebase optimized for one backend
• No configuration decisions about which database to use

Oracle AI Database Support

For enterprise deployments, Hindsight also supports Oracle AI Database with full feature parity. All memory operations—retain, recall, and reflect—work identically on Oracle, making it a drop-in option for organizations that standardize on Oracle infrastructure.

See the Oracle Database guide for setup: prerequisites, provisioning, connection URLs, migrations, and the differences from PostgreSQL.

Development with pg0

For local development, Hindsight uses pg0—an embedded PostgreSQL distribution.

What is pg0?

pg0 is a single binary containing:

• PostgreSQL server
• pgvector extension (pre-installed)
• Automatic initialization

Behavior

When no HINDSIGHT_API_DATABASE_URL is configured, Hindsight:

1. Starts an embedded PostgreSQL instance on port 5555
2. Initializes the schema
3. Stores data in ~/.hindsight/pg0/

Environments

Requirements

• PostgreSQL 15 or later
• pgvector 0.5.0 or later

Any PostgreSQL instance that satisfies these requirements should work. If you encounter issues with a specific setup, open a GitHub issue.

Tested Managed Services

• AWS RDS (PostgreSQL 15+)
• Google Cloud SQL
• Azure Database for PostgreSQL
• Supabase
• Neon