postgres

package
v0.16.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 19, 2026 License: AGPL-3.0 Imports: 10 Imported by: 0

Documentation

Overview

Package postgres implements oasis.Store and oasis.MemoryStore using PostgreSQL with pgvector for native vector similarity search and tsvector for full-text keyword search.

Both Store and MemoryStore accept an externally-owned *pgxpool.Pool via constructor injection. The caller creates and closes the pool.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ConfigurePoolConfig added in v0.10.0 

func ConfigurePoolConfig(cfg *pgxpool.Config, opts ...Option)

ConfigurePoolConfig applies store settings that require per-connection setup to a pgxpool.Config. Call this before pgxpool.NewWithConfig so every connection in the pool inherits the settings.

Currently applies: hnsw.ef_search (HNSW query-time candidate list size). If no relevant options are set, cfg is returned unmodified.

Types

type MemoryStore 

type MemoryStore struct {
	// contains filtered or unexported fields
}

MemoryStore implements oasis.MemoryStore backed by PostgreSQL with pgvector. Semantic deduplication uses pgvector cosine distance instead of brute-force.

func NewMemoryStore 

func NewMemoryStore(pool *pgxpool.Pool, opts ...Option) *MemoryStore

NewMemoryStore creates a MemoryStore using an existing pgxpool.Pool. The caller owns the pool and is responsible for closing it. Accepts the same Option functions as New (e.g. WithEmbeddingDimension, WithHNSWM, WithEFConstruction).

func (*MemoryStore) BuildContext 

func (s *MemoryStore) BuildContext(ctx context.Context, queryEmbedding []float32) (string, error)

BuildContext builds a markdown summary of known user facts for LLM context.

func (*MemoryStore) DecayOldFacts 

func (s *MemoryStore) DecayOldFacts(ctx context.Context) error

DecayOldFacts reduces confidence of stale facts and prunes very low ones. Facts older than 7 days get confidence * 0.95. Facts with confidence < 0.3 and age > 30 days are deleted.

func (*MemoryStore) DeleteFact 

func (s *MemoryStore) DeleteFact(ctx context.Context, factID string) error

DeleteFact removes a single fact by its ID.

func (*MemoryStore) DeleteMatchingFacts 

func (s *MemoryStore) DeleteMatchingFacts(ctx context.Context, pattern string) error

DeleteMatchingFacts removes facts whose text matches a LIKE pattern.

func (*MemoryStore) Init 

func (s *MemoryStore) Init(ctx context.Context) error

Init creates the pgvector extension, user_facts table, and HNSW index. Safe to call multiple times (all statements are idempotent).

Requires WithEmbeddingDimension to be set — pgvector HNSW indexes need typed vector(N) columns.

func (*MemoryStore) SearchFacts 

func (s *MemoryStore) SearchFacts(ctx context.Context, embedding []float32, topK int) ([]oasis.ScoredFact, error)

SearchFacts returns facts semantically similar to the query embedding, sorted by score descending. Only facts with confidence >= 0.3 are returned.

func (*MemoryStore) UpsertFact 

func (s *MemoryStore) UpsertFact(ctx context.Context, fact, category string, embedding []float32) error

UpsertFact inserts a new fact or merges with an existing one if cosine similarity exceeds 0.85. Merging updates the text and bumps confidence.

type Option added in v0.5.0 

type Option func(*pgConfig)

Option configures a PostgreSQL Store or MemoryStore.

func WithEFConstruction added in v0.5.0 

func WithEFConstruction(ef int) Option

WithEFConstruction sets the HNSW ef_construction parameter (build-time candidate list size). Higher values improve index quality at the cost of slower builds. Default: pgvector's 64. Only affects index creation (CREATE INDEX IF NOT EXISTS).

func WithEFSearch added in v0.5.0 

func WithEFSearch(ef int) Option

WithEFSearch sets the HNSW ef_search parameter (query-time candidate list size). Higher values improve recall at the cost of latency. Default: pgvector's 40. Applied via SET (session-level) during Init().

func WithEmbeddingDimension added in v0.5.0 

func WithEmbeddingDimension(dim int) Option

WithEmbeddingDimension sets the vector column dimension (e.g. 1536, 768). When set, CREATE TABLE uses vector(N) instead of untyped vector, enabling better index optimization and catching dimension mismatches at insert time. Only affects new table creation (no ALTER on existing tables).

func WithHNSWM added in v0.5.0 

func WithHNSWM(m int) Option

WithHNSWM sets the HNSW m parameter (max connections per node). Higher values improve recall at the cost of memory. Default: pgvector's 16. Only affects index creation (CREATE INDEX IF NOT EXISTS).

func WithLogger added in v0.10.0 

func WithLogger(l *slog.Logger) Option

WithLogger sets a structured logger for the store. When set, the store emits debug logs for every operation including timing, row counts, and key parameters. If not set, no logs are emitted.

type Store 

type Store struct {
	// contains filtered or unexported fields
}

Store implements oasis.Store backed by PostgreSQL with pgvector. Vector search uses HNSW indexes with cosine distance.

func New 

func New(pool *pgxpool.Pool, opts ...Option) *Store

New creates a Store using an existing pgxpool.Pool. The caller owns the pool and is responsible for closing it.

func (*Store) Close 

func (s *Store) Close() error

Close is a no-op. The caller owns the pool and manages its lifecycle.

func (*Store) CreateScheduledAction 

func (s *Store) CreateScheduledAction(ctx context.Context, action oasis.ScheduledAction) error

func (*Store) CreateThread 

func (s *Store) CreateThread(ctx context.Context, thread oasis.Thread) error

CreateThread inserts a new thread.

func (*Store) DeleteAllScheduledActions 

func (s *Store) DeleteAllScheduledActions(ctx context.Context) (int, error)

func (*Store) DeleteCheckpoint added in v0.10.0 

func (s *Store) DeleteCheckpoint(ctx context.Context, id string) error

DeleteCheckpoint removes an ingest checkpoint by ID.

func (*Store) DeleteDocument added in v0.5.0 

func (s *Store) DeleteDocument(ctx context.Context, id string) error

DeleteDocument removes a document and all its chunks in a single transaction.

func (*Store) DeleteScheduledAction 

func (s *Store) DeleteScheduledAction(ctx context.Context, id string) error

func (*Store) DeleteThread 

func (s *Store) DeleteThread(ctx context.Context, id string) error

DeleteThread removes a thread and its messages.

func (*Store) FindScheduledActionsByDescription 

func (s *Store) FindScheduledActionsByDescription(ctx context.Context, pattern string) ([]oasis.ScheduledAction, error)

func (*Store) GetBothEdges added in v0.10.0 

func (s *Store) GetBothEdges(ctx context.Context, chunkIDs []string) ([]oasis.ChunkEdge, error)

GetBothEdges returns both outgoing and incoming edges for the given chunk IDs in a single query. Implements oasis.BidirectionalGraphStore.

func (*Store) GetChunksByDocument added in v0.10.0 

func (s *Store) GetChunksByDocument(ctx context.Context, docID string) ([]oasis.Chunk, error)

GetChunksByDocument returns all chunks belonging to a specific document, including their embeddings. This implements ingest.DocumentChunkLister.

func (*Store) GetChunksByIDs 

func (s *Store) GetChunksByIDs(ctx context.Context, ids []string) ([]oasis.Chunk, error)

GetChunksByIDs returns chunks matching the given IDs.

func (*Store) GetConfig 

func (s *Store) GetConfig(ctx context.Context, key string) (string, error)

func (*Store) GetDocumentsByIDs added in v0.10.0 

func (s *Store) GetDocumentsByIDs(ctx context.Context, ids []string) ([]oasis.Document, error)

GetDocumentsByIDs returns documents matching the given IDs.

func (*Store) GetDueScheduledActions 

func (s *Store) GetDueScheduledActions(ctx context.Context, now int64) ([]oasis.ScheduledAction, error)

func (*Store) GetEdges added in v0.6.0 

func (s *Store) GetEdges(ctx context.Context, chunkIDs []string) ([]oasis.ChunkEdge, error)

func (*Store) GetIncomingEdges added in v0.6.0 

func (s *Store) GetIncomingEdges(ctx context.Context, chunkIDs []string) ([]oasis.ChunkEdge, error)

func (*Store) GetMessages 

func (s *Store) GetMessages(ctx context.Context, threadID string, limit int) ([]oasis.Message, error)

GetMessages returns the most recent messages for a thread, ordered chronologically (oldest first).

func (*Store) GetThread 

func (s *Store) GetThread(ctx context.Context, id string) (oasis.Thread, error)

GetThread returns a thread by ID.

func (*Store) Init 

func (s *Store) Init(ctx context.Context) error

Init creates the pgvector extension, all required tables, and indexes. Safe to call multiple times (all statements are idempotent).

Requires WithEmbeddingDimension to be set — pgvector HNSW indexes need typed vector(N) columns.

func (*Store) ListCheckpoints added in v0.10.0 

func (s *Store) ListCheckpoints(ctx context.Context) ([]oasis.IngestCheckpoint, error)

ListCheckpoints returns all stored ingest checkpoints.

func (*Store) ListDocumentMeta added in v0.10.0 

func (s *Store) ListDocumentMeta(ctx context.Context, limit int) ([]oasis.Document, error)

ListDocumentMeta returns all documents without the Content field, ordered by creation time (newest first). Use this instead of ListDocuments when only ID, Title, Source, and CreatedAt are needed to avoid loading large document bodies into memory.

func (*Store) ListDocuments added in v0.5.0 

func (s *Store) ListDocuments(ctx context.Context, limit int) ([]oasis.Document, error)

ListDocuments returns all documents ordered by most recently created first.

func (*Store) ListScheduledActions 

func (s *Store) ListScheduledActions(ctx context.Context) ([]oasis.ScheduledAction, error)

func (*Store) ListThreads 

func (s *Store) ListThreads(ctx context.Context, chatID string, limit int) ([]oasis.Thread, error)

ListThreads returns threads for a chatID, ordered by most recently updated first.

func (*Store) LoadCheckpoint added in v0.10.0 

func (s *Store) LoadCheckpoint(ctx context.Context, id string) (oasis.IngestCheckpoint, error)

LoadCheckpoint retrieves an ingest checkpoint by ID.

func (*Store) PruneOrphanEdges added in v0.6.0 

func (s *Store) PruneOrphanEdges(ctx context.Context) (int, error)

func (*Store) SaveCheckpoint added in v0.10.0 

func (s *Store) SaveCheckpoint(ctx context.Context, cp oasis.IngestCheckpoint) error

SaveCheckpoint upserts an ingest checkpoint by ID.

func (*Store) SearchChunks 

func (s *Store) SearchChunks(ctx context.Context, embedding []float32, topK int, filters ...oasis.ChunkFilter) ([]oasis.ScoredChunk, error)

SearchChunks performs vector similarity search over document chunks using pgvector's cosine distance operator with HNSW index.

func (*Store) SearchChunksKeyword 

func (s *Store) SearchChunksKeyword(ctx context.Context, query string, topK int, filters ...oasis.ChunkFilter) ([]oasis.ScoredChunk, error)

SearchChunksKeyword performs full-text keyword search over document chunks using PostgreSQL tsvector/tsquery with a GIN index.

func (*Store) SearchMessages 

func (s *Store) SearchMessages(ctx context.Context, embedding []float32, topK int) ([]oasis.ScoredMessage, error)

SearchMessages performs vector similarity search over messages using pgvector's cosine distance operator with HNSW index.

func (*Store) SetConfig 

func (s *Store) SetConfig(ctx context.Context, key, value string) error

func (*Store) StoreDocument 

func (s *Store) StoreDocument(ctx context.Context, doc oasis.Document, chunks []oasis.Chunk) error

StoreDocument inserts a document and all its chunks in a single transaction.

func (*Store) StoreEdges added in v0.6.0 

func (s *Store) StoreEdges(ctx context.Context, edges []oasis.ChunkEdge) error

func (*Store) StoreMessage 

func (s *Store) StoreMessage(ctx context.Context, msg oasis.Message) error

StoreMessage inserts or replaces a message.

func (*Store) UpdateScheduledAction 

func (s *Store) UpdateScheduledAction(ctx context.Context, action oasis.ScheduledAction) error

func (*Store) UpdateScheduledActionEnabled 

func (s *Store) UpdateScheduledActionEnabled(ctx context.Context, id string, enabled bool) error

func (*Store) UpdateThread 

func (s *Store) UpdateThread(ctx context.Context, thread oasis.Thread) error

UpdateThread updates a thread's title, metadata, and updated_at.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.