postgres

package
v1.1.0 Latest Latest
Warning

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

 Go to latest Published: Apr 13, 2026 License: Apache-2.0 Imports: 11 Imported by: 0

Documentation

Overview

Package postgres provides a PostgreSQL + pgvector implementation of the core.Store interface.

The store handles everything: connection, schema migration, embeddings, and retrieval. Callers only need to provide a DSN.

Usage: 

store, err := postgres.NewStore("postgres://postgres@localhost/loci?sslmode=disable")
if err != nil { ... }
defer store.Close()

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Migrate 

func Migrate(ctx context.Context, pool *pgxpool.Pool) error

Migrate ensures the database schema is up to date.

Types

type HealthCheckable 

type HealthCheckable interface {
	HealthCheck() error
}

HealthCheckable is implemented by the store.

type Migration 

type Migration struct {
	ID    int
	Name  string
	Apply func(ctx context.Context, pool *pgxpool.Pool) error
}

Migration defines a single schema change step.

type RetrieverConfig 

type RetrieverConfig struct {
	SemanticWeight       float64
	RecencyWeight        float64
	StrengthWeight       float64
	EndorsementWeight    float64
	MinStrength          float64
	GraphExpansion       string
	IntentBoostFactor    float64
	EnableIntentRouting  bool
	FilterContradictions bool
}

RetrieverConfig configures the scored retriever.

func DefaultRetrieverConfig 

func DefaultRetrieverConfig() RetrieverConfig

DefaultRetrieverConfig returns sensible defaults.

type ScoredRetriever 

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

ScoredRetriever implements core.Retriever using pgvector KNN + scoring.

func NewScoredRetriever 

func NewScoredRetriever(store *Store, embedder core.Embedder, cfg RetrieverConfig) *ScoredRetriever

NewScoredRetriever creates a retriever using pgvector KNN.

func (*ScoredRetriever) Retrieve 

func (r *ScoredRetriever) Retrieve(ctx context.Context, query core.RetrievalQuery) ([]core.ScoredFact, error)

Retrieve performs semantic + scoring retrieval.

type Store 

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

Store implements core.Store using PostgreSQL + pgvector.

func NewStore 

func NewStore(dsn string, cfg StoreConfig) (*Store, error)

NewStore connects to PostgreSQL, enables pgvector, and runs migrations. The caller is blind to internals — just pass a DSN.

Examples: 

postgres://postgres@localhost/loci?sslmode=disable
host=localhost user=postgres dbname=loci sslmode=disable

func (*Store) AddFactTags 

func (s *Store) AddFactTags(ctx context.Context, factID string, tags []string) error

func (*Store) ArchiveFacts 

func (s *Store) ArchiveFacts(ctx context.Context, factIDs []string) (int, error)

func (*Store) CleanWriteBackQueue added in v1.0.3 

func (s *Store) CleanWriteBackQueue(ctx context.Context, cutoffTimestamp int64) (int64, error)

func (*Store) ClearEmbeddings 

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

func (*Store) Close 

func (s *Store) Close() error

func (*Store) CompleteWriteBack 

func (s *Store) CompleteWriteBack(ctx context.Context, id int64) error

func (*Store) ComputeMemoryDiff 

func (s *Store) ComputeMemoryDiff(ctx context.Context, entityID string, fromTime, toTime int64) (*core.MemoryDiff, error)

func (*Store) CreateSnapshot 

func (s *Store) CreateSnapshot(ctx context.Context, entityID string) (*core.MemorySnapshot, error)

func (*Store) DecayAllFacts added in v1.0.3 

func (s *Store) DecayAllFacts(ctx context.Context, decayFactor float64, archiveBelow float64) (int64, error)

func (*Store) DeleteEntity 

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

func (*Store) DeleteEpisodesByEntity 

func (s *Store) DeleteEpisodesByEntity(ctx context.Context, entityID string) error

func (*Store) DeleteFactRelations 

func (s *Store) DeleteFactRelations(ctx context.Context, factID string) error

func (*Store) DeleteFactsByEntity 

func (s *Store) DeleteFactsByEntity(ctx context.Context, entityID string) error

func (*Store) DeleteNotification 

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

func (*Store) DeleteOldNotifications 

func (s *Store) DeleteOldNotifications(ctx context.Context, cutoffTime int64) (int64, error)

func (*Store) DeleteSessionsByEntity 

func (s *Store) DeleteSessionsByEntity(ctx context.Context, entityID string) error

func (*Store) DeleteSessionsOlderThan 

func (s *Store) DeleteSessionsOlderThan(ctx context.Context, cutoffTime int64) (int64, error)

func (*Store) DequeueWriteBack 

func (s *Store) DequeueWriteBack(ctx context.Context) (*core.WriteBackQueueItem, error)

func (*Store) EnqueueWriteBack 

func (s *Store) EnqueueWriteBack(ctx context.Context, payload string) (int64, error)

func (*Store) FailWriteBack 

func (s *Store) FailWriteBack(ctx context.Context, id int64) error

func (*Store) FollowEntity 

func (s *Store) FollowEntity(ctx context.Context, follow core.EntityFollow) error

func (*Store) GetAllEntities 

func (s *Store) GetAllEntities(ctx context.Context) ([]core.Entity, error)

func (*Store) GetChangelog 

func (s *Store) GetChangelog(ctx context.Context, entityID string, fromTime, toTime int64, limit, offset int) ([]core.FactChangelogEntry, error)

func (*Store) GetEmbedding 

func (s *Store) GetEmbedding(ctx context.Context, factID string) ([]float32, error)

func (*Store) GetEmbeddingCount 

func (s *Store) GetEmbeddingCount(ctx context.Context) (int64, error)

func (*Store) GetEmbeddingMetadata 

func (s *Store) GetEmbeddingMetadata(ctx context.Context) (*core.EmbeddingMetadata, error)

func (*Store) GetEntity 

func (s *Store) GetEntity(ctx context.Context, id string) (*core.Entity, error)

func (*Store) GetEpisode 

func (s *Store) GetEpisode(ctx context.Context, id string) (*core.Episode, error)

func (*Store) GetFact 

func (s *Store) GetFact(ctx context.Context, id string) (*core.Fact, error)

func (*Store) GetFactCount 

func (s *Store) GetFactCount(ctx context.Context) (int64, error)

func (*Store) GetFactLineage 

func (s *Store) GetFactLineage(ctx context.Context, factID string) (*core.FactLineage, error)

func (*Store) GetFactRelations 

func (s *Store) GetFactRelations(ctx context.Context, factID string) ([]core.FactRelation, error)

func (*Store) GetFactRelationsBatch added in v1.1.0 

func (s *Store) GetFactRelationsBatch(ctx context.Context, factIDs []string) (map[string][]core.FactRelation, error)

func (*Store) GetFactTags 

func (s *Store) GetFactTags(ctx context.Context, factID string) ([]string, error)

func (*Store) GetFactsByEntity 

func (s *Store) GetFactsByEntity(ctx context.Context, entityID string) ([]core.Fact, error)

func (*Store) GetFactsByIDs added in v1.1.0 

func (s *Store) GetFactsByIDs(ctx context.Context, ids []string) ([]core.Fact, error)

func (*Store) GetFollowers 

func (s *Store) GetFollowers(ctx context.Context, followingEntityID string) ([]core.EntityFollow, error)

func (*Store) GetFollowing 

func (s *Store) GetFollowing(ctx context.Context, followerEntityID string) ([]core.EntityFollow, error)

func (*Store) GetNotifications 

func (s *Store) GetNotifications(ctx context.Context, entityID string, unreadOnly bool) ([]core.Notification, error)

func (*Store) GetRelatedEntities 

func (s *Store) GetRelatedEntities(ctx context.Context, entityID string, depth int) ([]core.EntityRelation, error)

func (*Store) GetSession 

func (s *Store) GetSession(ctx context.Context, sessionID string) (*core.Session, error)

func (*Store) GetSessionTurns 

func (s *Store) GetSessionTurns(ctx context.Context, sessionID string) ([]core.SessionTurn, error)

func (*Store) GetSessionsByEntity 

func (s *Store) GetSessionsByEntity(ctx context.Context, entityID string) ([]core.Session, error)

func (*Store) GetSnapshots 

func (s *Store) GetSnapshots(ctx context.Context, entityID string) ([]core.MemorySnapshot, error)

func (*Store) GetTemporalFactsByEntity added in v1.1.0 

func (s *Store) GetTemporalFactsByEntity(ctx context.Context, entityID string) ([]core.Fact, error)

func (*Store) GetTimeline 

func (s *Store) GetTimeline(ctx context.Context, entityID string, days int) ([]core.DaySummary, error)

func (*Store) GetUnconsolidatedEpisodes 

func (s *Store) GetUnconsolidatedEpisodes(ctx context.Context, entityID string) ([]core.Episode, error)

func (*Store) GetWriteBackStats 

func (s *Store) GetWriteBackStats(ctx context.Context) (core.WriteBackStats, error)

func (*Store) HealthCheck 

func (s *Store) HealthCheck() error

func (*Store) MarkConsolidated 

func (s *Store) MarkConsolidated(ctx context.Context, episodeID string) error

func (*Store) MarkNotificationRead 

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

func (*Store) Ping 

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

func (*Store) Pool 

func (s *Store) Pool() *pgxpool.Pool

Pool returns the underlying connection pool (for admin operations).

func (*Store) RecordSessionFact 

func (s *Store) RecordSessionFact(ctx context.Context, sessionID, factID string) error

func (*Store) RecordSessionTurn 

func (s *Store) RecordSessionTurn(ctx context.Context, turn core.SessionTurn) error

func (*Store) RecoverPendingWriteBacks 

func (s *Store) RecoverPendingWriteBacks(ctx context.Context) ([]core.WriteBackQueueItem, error)

func (*Store) SearchFacts 

func (s *Store) SearchFacts(ctx context.Context, query core.SearchQuery) ([]core.ScoredFact, error)

func (*Store) SearchFactsByTags 

func (s *Store) SearchFactsByTags(ctx context.Context, tags []string, limit int) ([]core.ScoredFact, error)

func (*Store) SetEmbeddingMetadata 

func (s *Store) SetEmbeddingMetadata(ctx context.Context, modelName string, dimensions int) error

func (*Store) StoreEmbedding 

func (s *Store) StoreEmbedding(ctx context.Context, factID string, embedding []float32) error

func (*Store) SupersedeFact 

func (s *Store) SupersedeFact(ctx context.Context, oldID, newID string) error

func (*Store) UnfollowEntity 

func (s *Store) UnfollowEntity(ctx context.Context, followerEntityID, followingEntityID string) error

func (*Store) UpsertEntity 

func (s *Store) UpsertEntity(ctx context.Context, entity core.Entity) error

func (*Store) WriteChangelog 

func (s *Store) WriteChangelog(ctx context.Context, entry core.FactChangelogEntry) error

func (*Store) WriteEntityRelations 

func (s *Store) WriteEntityRelations(ctx context.Context, relations []core.EntityRelation) error

func (*Store) WriteEpisode 

func (s *Store) WriteEpisode(ctx context.Context, ep core.Episode) error

func (*Store) WriteEpisodes 

func (s *Store) WriteEpisodes(ctx context.Context, episodes []core.Episode) (*core.BatchResult, error)

func (*Store) WriteFact 

func (s *Store) WriteFact(ctx context.Context, fact core.Fact) error

func (*Store) WriteFactRelation 

func (s *Store) WriteFactRelation(ctx context.Context, rel core.FactRelation) error

func (*Store) WriteFacts 

func (s *Store) WriteFacts(ctx context.Context, facts []core.Fact) (*core.BatchResult, error)

func (*Store) WriteNotification 

func (s *Store) WriteNotification(ctx context.Context, n core.Notification) error

func (*Store) WriteSession 

func (s *Store) WriteSession(ctx context.Context, session core.Session) error

type StoreConfig added in v1.1.0 

type StoreConfig struct {
	MaxConns        int32
	MinConns        int32
	MaxConnLifetime time.Duration
	MaxConnIdleTime time.Duration
	QueryTimeout    time.Duration
}

StoreConfig configures the PostgreSQL connection pool.

func DefaultStoreConfig added in v1.1.0 

func DefaultStoreConfig() StoreConfig

DefaultStoreConfig returns safe production defaults.

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.