PostgreSQL Store

The store/postgres package provides a production-ready implementation of the composite store.Store interface using PostgreSQL with the Grove ORM and pgdriver.

Setup

import (
    "github.com/xraph/grove"
    "github.com/xraph/grove/drivers/pgdriver"
    "github.com/xraph/cortex/store/postgres"
)

// Open a PostgreSQL connection via Grove's pgdriver.
db := grove.Open(pgdriver.New(
    pgdriver.WithDSN("postgres://user:pass@localhost:5432/cortex?sslmode=disable"),
))

s := postgres.New(db)
if err := s.Migrate(ctx); err != nil {
    log.Fatal(err)
}

Internals

Tables

JSONB columns

Complex nested structures are stored as JSONB columns:

• Skill tools and knowledge -- tools JSONB, knowledge JSONB
• Trait dimensions and influences -- dimensions JSONB, influences JSONB
• Behavior triggers and actions -- triggers JSONB, actions JSONB
• Persona styles -- cognitive_style JSONB, communication_style JSONB, perception JSONB
• All entities -- metadata JSONB

Composite store interface

The PostgreSQL store implements all 8 sub-interfaces:

type Store interface {
    agent.Store      // 6 methods
    skill.Store      // 6 methods
    trait.Store      // 6 methods
    behavior.Store   // 6 methods
    persona.Store    // 6 methods
    run.Store        // 8 methods
    memory.Store     // 8 methods
    checkpoint.Store // 4 methods

    Migrate(ctx context.Context) error
    Ping(ctx context.Context) error
    Close() error
}

Embedded migrations

Migrations are embedded in the binary and run automatically when Migrate() is called. There is no need for external migration tools.

Usage with engine

eng, err := engine.New(
    engine.WithStore(s),
)

When to use

• Production deployments -- durable, ACID-compliant storage with connection pooling.
• Multi-instance deployments -- all application instances share the same database.
• Teams already using PostgreSQL -- leverage existing infrastructure and expertise.