storage

package
v0.0.0-...-a3bda8b Latest Latest
Warning

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

 Go to latest Published: Apr 6, 2026 License: MIT Imports: 19 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var MigrationSQL string

MigrationSQL holds the initial schema. Set by the main package at startup using the embedded migrations file, or hardcoded for tests.

Functions

This section is empty.

Types

type JobUpdate 

type JobUpdate struct {
	EpisodeID string
	Result    json.RawMessage
	Error     string
}

JobUpdate holds optional fields for status transitions.

type SQLiteStore 

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

SQLiteStore implements Store backed by SQLite.

func NewSQLiteStore 

func NewSQLiteStore(dbPath string) (*SQLiteStore, error)

NewSQLiteStore opens or creates a SQLite database at the given path. Pass ":memory:" for an in-memory database (useful for testing).

func (*SQLiteStore) BatchUpdateDecayStrength 

func (s *SQLiteStore) BatchUpdateDecayStrength(ctx context.Context, kbID string, halfLifeHours float64) (int64, error)

BatchUpdateDecayStrength applies exponential decay to all items in a KB in a single SQL UPDATE. Returns the number of rows updated.

func (*SQLiteStore) Close 

func (s *SQLiteStore) Close() error

func (*SQLiteStore) CountEpisodesBySourcePrefix 

func (s *SQLiteStore) CountEpisodesBySourcePrefix(ctx context.Context, kbID, prefix string) (int, error)

CountEpisodesBySourcePrefix counts episodes whose source starts with the given prefix.

func (*SQLiteStore) CreateCommunity 

func (s *SQLiteStore) CreateCommunity(ctx context.Context, c *domain.Community) error

func (*SQLiteStore) CreateEntity 

func (s *SQLiteStore) CreateEntity(ctx context.Context, e *domain.Entity) error

func (*SQLiteStore) CreateEpisode 

func (s *SQLiteStore) CreateEpisode(ctx context.Context, ep *domain.Episode) error

func (*SQLiteStore) CreateFeedback 

func (s *SQLiteStore) CreateFeedback(ctx context.Context, fb *domain.Feedback) error

CreateFeedback persists a feedback record.

func (*SQLiteStore) CreateJob 

func (s *SQLiteStore) CreateJob(ctx context.Context, job *domain.IngestionJob) error

func (*SQLiteStore) CreateKB 

func (s *SQLiteStore) CreateKB(ctx context.Context, kb *domain.KnowledgeBase) error

func (*SQLiteStore) CreateRelation 

func (s *SQLiteStore) CreateRelation(ctx context.Context, r *domain.Relation) error

func (*SQLiteStore) DB 

func (s *SQLiteStore) DB() *sql.DB

func (*SQLiteStore) DBSize 

func (s *SQLiteStore) DBSize() (int64, error)

DBSize returns the database file size in bytes.

func (*SQLiteStore) DeduplicateRelationsForEntity 

func (s *SQLiteStore) DeduplicateRelationsForEntity(ctx context.Context, kbID, entityID string) (int64, error)

DeduplicateRelationsForEntity deduplicates active edges involving a specific entity. Returns the number of relation rows deleted.

func (*SQLiteStore) DeduplicateRelationsForKB 

func (s *SQLiteStore) DeduplicateRelationsForKB(ctx context.Context, kbID string) (int64, error)

DeduplicateRelationsForKB finds and merges all duplicate active edges in a knowledge base. Duplicate edges share the same (source_id, target_id, type). Self-loops are also removed. Returns the number of relation rows deleted.

func (*SQLiteStore) DeleteDecayState 

func (s *SQLiteStore) DeleteDecayState(ctx context.Context, kbID, entityType, entityID string) error

DeleteDecayState removes the decay state for a specific item.

func (*SQLiteStore) DeleteEntity 

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

func (*SQLiteStore) DeleteEpisode 

func (s *SQLiteStore) DeleteEpisode(ctx context.Context, kbID, id string) error

func (*SQLiteStore) DeleteKB 

func (s *SQLiteStore) DeleteKB(ctx context.Context, id string) error

func (*SQLiteStore) DequeueJobs 

func (s *SQLiteStore) DequeueJobs(ctx context.Context, limit int) ([]*domain.IngestionJob, error)

DequeueJobs atomically claims up to limit "queued" jobs by setting them to "running". All data is read in a single transaction to avoid N+1 re-reads.

func (*SQLiteStore) FindEntitiesByName 

func (s *SQLiteStore) FindEntitiesByName(ctx context.Context, kbID, name string) ([]*domain.Entity, error)

func (*SQLiteStore) GetDecayState 

func (s *SQLiteStore) GetDecayState(ctx context.Context, kbID, entityType, entityID string) (*domain.DecayState, error)

func (*SQLiteStore) GetEntitiesByIDs 

func (s *SQLiteStore) GetEntitiesByIDs(ctx context.Context, kbID string, ids []string) (map[string]*domain.Entity, error)

func (*SQLiteStore) GetEntity 

func (s *SQLiteStore) GetEntity(ctx context.Context, kbID, id string) (*domain.Entity, error)

func (*SQLiteStore) GetEpisode 

func (s *SQLiteStore) GetEpisode(ctx context.Context, kbID, id string) (*domain.Episode, error)

func (*SQLiteStore) GetFeedbackStats 

func (s *SQLiteStore) GetFeedbackStats(ctx context.Context, kbID string) (*domain.FeedbackStats, error)

GetFeedbackStats returns aggregate feedback metrics for a KB.

func (*SQLiteStore) GetJob 

func (s *SQLiteStore) GetJob(ctx context.Context, id string) (*domain.IngestionJob, error)

func (*SQLiteStore) GetKB 

func (s *SQLiteStore) GetKB(ctx context.Context, id string) (*domain.KnowledgeBase, error)

func (*SQLiteStore) GetRelation 

func (s *SQLiteStore) GetRelation(ctx context.Context, kbID, id string) (*domain.Relation, error)

func (*SQLiteStore) GetRelationsByIDs 

func (s *SQLiteStore) GetRelationsByIDs(ctx context.Context, kbID string, ids []string) (map[string]*domain.Relation, error)

func (*SQLiteStore) GetRelationsForEntity 

func (s *SQLiteStore) GetRelationsForEntity(ctx context.Context, kbID, entityID string) ([]*domain.Relation, error)

func (*SQLiteStore) GetStats 

func (s *SQLiteStore) GetStats(ctx context.Context, kbID string) (*domain.MemoryStats, error)

func (*SQLiteStore) GetSubgraphEntitiesByIDs 

func (s *SQLiteStore) GetSubgraphEntitiesByIDs(ctx context.Context, kbID string, ids []string) (map[string]SubgraphEntityMetadata, error)

GetSubgraphEntitiesByIDs returns lightweight entity metadata for subgraph hydration.

func (*SQLiteStore) GetSubgraphRelationsByIDs 

func (s *SQLiteStore) GetSubgraphRelationsByIDs(ctx context.Context, kbID string, ids []string) (map[string]SubgraphRelationMetadata, error)

GetSubgraphRelationsByIDs returns lightweight relation metadata for subgraph hydration.

func (*SQLiteStore) GetValidRelations 

func (s *SQLiteStore) GetValidRelations(ctx context.Context, kbID string, at time.Time) ([]*domain.Relation, error)

func (*SQLiteStore) InvalidateRelation 

func (s *SQLiteStore) InvalidateRelation(ctx context.Context, kbID, id string, invalidAt time.Time) error

func (*SQLiteStore) ListCommunities 

func (s *SQLiteStore) ListCommunities(ctx context.Context, kbID string) ([]*domain.Community, error)

func (*SQLiteStore) ListDecayStates 

func (s *SQLiteStore) ListDecayStates(ctx context.Context, kbID string, maxStrength float64) ([]*domain.DecayState, error)

func (*SQLiteStore) ListEntities 

func (s *SQLiteStore) ListEntities(ctx context.Context, kbID string, limit, offset int) ([]*domain.Entity, error)

func (*SQLiteStore) ListEntityNames 

func (s *SQLiteStore) ListEntityNames(ctx context.Context, kbID string) ([]*domain.Entity, error)

ListEntityNames returns all entities for a KB with only id, name, type, summary populated. Skips embedding BLOBs for efficiency during entity resolution.

func (*SQLiteStore) ListEpisodes 

func (s *SQLiteStore) ListEpisodes(ctx context.Context, kbID string, limit, offset int) ([]*domain.Episode, error)

func (*SQLiteStore) ListFeedbackByTopic 

func (s *SQLiteStore) ListFeedbackByTopic(ctx context.Context, kbID, topic string, limit int) ([]*domain.Feedback, error)

ListFeedbackByTopic lists feedback for a specific topic.

func (*SQLiteStore) ListJobs 

func (s *SQLiteStore) ListJobs(ctx context.Context, kbID, status string, limit int) ([]*domain.IngestionJob, error)

func (*SQLiteStore) ListKBs 

func (s *SQLiteStore) ListKBs(ctx context.Context) ([]*domain.KnowledgeBase, error)

func (*SQLiteStore) ListRelations 

func (s *SQLiteStore) ListRelations(ctx context.Context, kbID string, limit, offset int) ([]*domain.Relation, error)

func (*SQLiteStore) LoadEntityEmbeddings 

func (s *SQLiteStore) LoadEntityEmbeddings(ctx context.Context, kbID string) (map[string][]float32, error)

LoadEntityEmbeddings returns all entity embeddings for a KB as id -> []float32. Used to hydrate the in-memory vector index at startup.

func (*SQLiteStore) LoadRelationEmbeddings 

func (s *SQLiteStore) LoadRelationEmbeddings(ctx context.Context, kbID string) (map[string][]float32, error)

LoadRelationEmbeddings returns all valid relation embeddings for a KB as id -> []float32.

func (*SQLiteStore) LogAccess 

func (s *SQLiteStore) LogAccess(ctx context.Context, kbID, entityType, entityID string) error

func (*SQLiteStore) RecoverStaleJobs 

func (s *SQLiteStore) RecoverStaleJobs(ctx context.Context) (int64, error)

RecoverStaleJobs resets jobs stuck in "running" for more than 5 minutes (e.g. after crash) back to "queued" for retry.

func (*SQLiteStore) RedirectRelations 

func (s *SQLiteStore) RedirectRelations(ctx context.Context, kbID, fromEntityID, toEntityID string) (int64, error)

RedirectRelations rewrites all active relations pointing at fromEntityID to point at toEntityID. Both updates run in a single transaction. Returns the number of updated rows.

func (*SQLiteStore) SearchFTS 

func (s *SQLiteStore) SearchFTS(ctx context.Context, kbID, query string, limit int) ([]*domain.SearchResult, error)

SearchFTS performs a BM25 full-text search across entities, relations, and episodes within a knowledge base. Results are ranked by FTS5 relevance.

func (*SQLiteStore) SearchFeedback 

func (s *SQLiteStore) SearchFeedback(ctx context.Context, kbID, query string, limit int) ([]*domain.Feedback, error)

SearchFeedback searches feedback using FTS5 full-text search.

func (*SQLiteStore) SearchVectorEntities 

func (s *SQLiteStore) SearchVectorEntities(ctx context.Context, kbID string, query []float32, limit int) ([]*domain.SearchResult, error)

SearchVectorEntities performs brute-force cosine similarity search over entity embeddings stored in the database. For indexed search, use vecstore.Engine.

func (*SQLiteStore) SearchVectorRelations 

func (s *SQLiteStore) SearchVectorRelations(ctx context.Context, kbID string, query []float32, limit int) ([]*domain.SearchResult, error)

SearchVectorRelations performs brute-force cosine similarity search over relation embeddings.

func (*SQLiteStore) UpdateCommunity 

func (s *SQLiteStore) UpdateCommunity(ctx context.Context, c *domain.Community) error

func (*SQLiteStore) UpdateDecayState 

func (s *SQLiteStore) UpdateDecayState(ctx context.Context, ds *domain.DecayState) error

func (*SQLiteStore) UpdateEntity 

func (s *SQLiteStore) UpdateEntity(ctx context.Context, e *domain.Entity) error

func (*SQLiteStore) UpdateJobStatus 

func (s *SQLiteStore) UpdateJobStatus(ctx context.Context, id, status string, updates JobUpdate) error

func (*SQLiteStore) UpsertRelation 

func (s *SQLiteStore) UpsertRelation(ctx context.Context, r *domain.Relation) (bool, error)

UpsertRelation creates a new relation or strengthens an existing active edge with the same (source, target, type) tuple. Returns true if a new relation was created.

type Store 

type Store interface {
	// Knowledge Bases
	CreateKB(ctx context.Context, kb *domain.KnowledgeBase) error
	GetKB(ctx context.Context, id string) (*domain.KnowledgeBase, error)
	ListKBs(ctx context.Context) ([]*domain.KnowledgeBase, error)
	DeleteKB(ctx context.Context, id string) error

	// Episodes
	CreateEpisode(ctx context.Context, ep *domain.Episode) error
	GetEpisode(ctx context.Context, kbID, id string) (*domain.Episode, error)
	ListEpisodes(ctx context.Context, kbID string, limit, offset int) ([]*domain.Episode, error)
	DeleteEpisode(ctx context.Context, kbID, id string) error

	// Entities
	CreateEntity(ctx context.Context, e *domain.Entity) error
	GetEntity(ctx context.Context, kbID, id string) (*domain.Entity, error)
	GetEntitiesByIDs(ctx context.Context, kbID string, ids []string) (map[string]*domain.Entity, error)
	UpdateEntity(ctx context.Context, e *domain.Entity) error
	DeleteEntity(ctx context.Context, kbID, id string) error
	FindEntitiesByName(ctx context.Context, kbID, name string) ([]*domain.Entity, error)
	ListEntities(ctx context.Context, kbID string, limit, offset int) ([]*domain.Entity, error)
	ListEntityNames(ctx context.Context, kbID string) ([]*domain.Entity, error) // lightweight: id, name, type, summary only

	// Relations
	CreateRelation(ctx context.Context, r *domain.Relation) error
	GetRelation(ctx context.Context, kbID, id string) (*domain.Relation, error)
	GetRelationsByIDs(ctx context.Context, kbID string, ids []string) (map[string]*domain.Relation, error)
	InvalidateRelation(ctx context.Context, kbID, id string, invalidAt time.Time) error
	GetRelationsForEntity(ctx context.Context, kbID, entityID string) ([]*domain.Relation, error)
	GetValidRelations(ctx context.Context, kbID string, at time.Time) ([]*domain.Relation, error)
	ListRelations(ctx context.Context, kbID string, limit, offset int) ([]*domain.Relation, error)
	UpsertRelation(ctx context.Context, r *domain.Relation) (bool, error)
	DeduplicateRelationsForKB(ctx context.Context, kbID string) (int64, error)
	DeduplicateRelationsForEntity(ctx context.Context, kbID, entityID string) (int64, error)

	// Communities
	CreateCommunity(ctx context.Context, c *domain.Community) error
	UpdateCommunity(ctx context.Context, c *domain.Community) error
	ListCommunities(ctx context.Context, kbID string) ([]*domain.Community, error)

	// FTS5 search
	SearchFTS(ctx context.Context, kbID, query string, limit int) ([]*domain.SearchResult, error)

	// Vector search — loads embeddings from DB for brute-force similarity search.
	// For high-performance indexed search, use the vecstore.Engine directly.
	SearchVectorEntities(ctx context.Context, kbID string, query []float32, limit int) ([]*domain.SearchResult, error)
	SearchVectorRelations(ctx context.Context, kbID string, query []float32, limit int) ([]*domain.SearchResult, error)

	// Access tracking
	LogAccess(ctx context.Context, kbID, entityType, entityID string) error
	GetDecayState(ctx context.Context, kbID, entityType, entityID string) (*domain.DecayState, error)
	UpdateDecayState(ctx context.Context, ds *domain.DecayState) error
	ListDecayStates(ctx context.Context, kbID string, maxStrength float64) ([]*domain.DecayState, error)

	// Stats
	GetStats(ctx context.Context, kbID string) (*domain.MemoryStats, error)

	// Ingestion jobs
	CreateJob(ctx context.Context, job *domain.IngestionJob) error
	GetJob(ctx context.Context, id string) (*domain.IngestionJob, error)
	ListJobs(ctx context.Context, kbID, status string, limit int) ([]*domain.IngestionJob, error)
	UpdateJobStatus(ctx context.Context, id, status string, updates JobUpdate) error
	RecoverStaleJobs(ctx context.Context) (int64, error)
	DequeueJobs(ctx context.Context, limit int) ([]*domain.IngestionJob, error)

	// Vector loading — used for vecstore hydration at startup or on first search.
	LoadEntityEmbeddings(ctx context.Context, kbID string) (map[string][]float32, error)
	LoadRelationEmbeddings(ctx context.Context, kbID string) (map[string][]float32, error)

	// Episode counts
	CountEpisodesBySourcePrefix(ctx context.Context, kbID, prefix string) (int, error)

	// Feedback
	CreateFeedback(ctx context.Context, fb *domain.Feedback) error
	SearchFeedback(ctx context.Context, kbID, query string, limit int) ([]*domain.Feedback, error)
	ListFeedbackByTopic(ctx context.Context, kbID, topic string, limit int) ([]*domain.Feedback, error)
	GetFeedbackStats(ctx context.Context, kbID string) (*domain.FeedbackStats, error)

	// Consolidation
	RedirectRelations(ctx context.Context, kbID, fromEntityID, toEntityID string) (int64, error)
	DeleteDecayState(ctx context.Context, kbID, entityType, entityID string) error
	BatchUpdateDecayStrength(ctx context.Context, kbID string, halfLifeHours float64) (int64, error)

	// Lifecycle
	Close() error
	DB() *sql.DB
}

Store provides all database operations scoped by knowledge base.

type SubgraphEntityMetadata 

type SubgraphEntityMetadata struct {
	ID      string
	Name    string
	Type    string
	Summary string
}

SubgraphEntityMetadata is the lightweight entity shape needed to hydrate a subgraph.

type SubgraphRelationMetadata 

type SubgraphRelationMetadata struct {
	ID        string
	SourceID  string
	TargetID  string
	Type      string
	Weight    float64
	ValidAt   time.Time
	InvalidAt *time.Time
}

SubgraphRelationMetadata is the lightweight relation shape needed to hydrate a subgraph.

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.