events

Documentation

Overview

Package events provides temporal event storage with semantic search capabilities.

Index

• type Event
• type EventStore
  • func NewEventStore(db *sql.DB, embedder embeddings.Embedder) *EventStore
  • func (s *EventStore) CountEvents(ctx context.Context) (int64, error)
  • func (s *EventStore) DeleteEvent(ctx context.Context, id int64) error
  • func (s *EventStore) ListEvents(ctx context.Context, subject string, limit, offset int) ([]Event, error)
  • func (s *EventStore) RebuildFTS(ctx context.Context) error
  • func (s *EventStore) SaveEvent(ctx context.Context, subject, content string, metadata map[string]interface{}) (int64, error)
  • func (s *EventStore) SearchEvents(ctx context.Context, opts SearchOptions) ([]SearchResult, error)
• type SearchOptions
• type SearchResult

Types

type Event

type Event struct {
	// ID is the database row ID (set after insert, zero for new events).
	ID int64
	// Subject categorizes the event (e.g. user ID, session ID, topic).
	Subject string
	// Content is the event text content.
	Content string
	// Metadata is an arbitrary JSON string stored alongside the event.
	Metadata map[string]interface{}
	// EventAt is when the event occurred (defaults to creation time).
	EventAt time.Time
	// CreatedAt is when the event was stored in the database.
	CreatedAt time.Time
}

Event represents a temporal event with optional semantic search.

type EventStore

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

EventStore manages temporal events with semantic search capabilities.

func NewEventStore

func NewEventStore(db *sql.DB, embedder embeddings.Embedder) *EventStore

NewEventStore creates a new EventStore backed by db. The embedder is used to generate embeddings for event content.

func (*EventStore) CountEvents

func (s *EventStore) CountEvents(ctx context.Context) (int64, error)

CountEvents returns the total number of events.

func (*EventStore) DeleteEvent

func (s *EventStore) DeleteEvent(ctx context.Context, id int64) error

DeleteEvent removes an event and its FTS entry. It is a no-op when the event does not exist.

func (*EventStore) ListEvents

func (s *EventStore) ListEvents(ctx context.Context, subject string, limit, offset int) ([]Event, error)

ListEvents returns paginated events filtered by subject (all when subject="").

func (*EventStore) RebuildFTS

func (s *EventStore) RebuildFTS(ctx context.Context) error

RebuildFTS rebuilds the FTS5 index from the events content table. Use this to recover from index corruption or after bulk inserts that bypassed the normal SaveEvent path.

func (*EventStore) SaveEvent

func (s *EventStore) SaveEvent(ctx context.Context, subject, content string, metadata map[string]interface{}) (int64, error)

SaveEvent stores a new event with its embedding and updates the FTS index. The embedding is generated from the content using the configured embedder. Returns the auto-assigned event ID.

func (*EventStore) SearchEvents

func (s *EventStore) SearchEvents(ctx context.Context, opts SearchOptions) ([]SearchResult, error)

SearchEvents performs hybrid search with temporal filters. The search combines vector similarity and FTS using RRF, then applies time filters.

type SearchOptions

type SearchOptions struct {
	// Query is the search text (used for both vector and FTS search).
	Query string
	// Subject restricts results to events with this subject (empty means all).
	Subject string
	// FromDate filters events that occurred on or after this time (inclusive).
	FromDate *time.Time
	// ToDate filters events that occurred on or before this time (inclusive).
	ToDate *time.Time
	// LastHours filters events from the last N hours (overrides FromDate).
	LastHours int
	// LastDays filters events from the last N days (overrides FromDate).
	LastDays int
	// Limit is the maximum number of results to return (defaults to 10).
	Limit int
}

SearchOptions controls event search behaviour.

type SearchResult

type SearchResult struct {
	Event Event
	// Score is a normalised relevance score in [0, 1] where higher is better.
	// For vector search:  cosine similarity.
	// For FTS search:     normalised BM25.
	// For hybrid search:  Reciprocal Rank Fusion score.
	Score float64
	// Rank is the 1-based position in the result list.
	Rank int
}

SearchResult is a ranked event returned from search.