Documentation
¶
Overview ¶
Package store implements the persistence layer for Coggo v0.1.
The backend is SQLite (via ncruces/go-sqlite3) augmented with the sqlite-vec extension for vector similarity search. A single SQLite database backs the whole binary; per-peer isolation is enforced at the application layer by tagging every row with PeerDID.
See .ai/docs/decisions.md for the rationale on choosing SQLite over the originally planned SurrealDB embedded backend.
Index ¶
- type Store
- func (s *Store) AppendEvent(ctx context.Context, ev *types.Event) error
- func (s *Store) ArchiveEntity(ctx context.Context, peerDID, id string, at time.Time) error
- func (s *Store) Close() error
- func (s *Store) DB() *sql.DB
- func (s *Store) DissolveRelation(ctx context.Context, peerDID, id string) error
- func (s *Store) GetEntity(ctx context.Context, peerDID, id string) (*types.Entity, error)
- func (s *Store) Init(ctx context.Context) error
- func (s *Store) ListEvents(ctx context.Context, peerDID string, since, until time.Time) ([]*types.Event, error)
- func (s *Store) QueryEntities(ctx context.Context, peerDID string, q types.EntityQuery) ([]*types.Entity, error)
- func (s *Store) QueryRelations(ctx context.Context, peerDID, from, to, relType string, limit int) ([]*types.Relation, error)
- func (s *Store) SemanticSearch(ctx context.Context, peerDID string, vector []float32, typeFilter string, ...) ([]types.SemanticHit, error)
- func (s *Store) SubstringSearch(ctx context.Context, peerDID, query, typeFilter string, limit int) ([]types.SemanticHit, error)
- func (s *Store) TimeTravelEntities(ctx context.Context, peerDID string, q types.EntityQuery, asOf time.Time) ([]*types.Entity, error)
- func (s *Store) UpsertEmbedding(ctx context.Context, peerDID, entityID string, vector []float32, model string) error
- func (s *Store) UpsertEntity(ctx context.Context, e *types.Entity) error
- func (s *Store) UpsertRelation(ctx context.Context, r *types.Relation) error
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
Store is the SQLite-backed implementation of types.Store.
func New ¶
New constructs a Store backed by a SQLite database at the given path. The dim argument fixes the dimensionality of vectors stored in the entity_embeddings vec0 virtual table; it must match the embedder used to generate vectors that will be inserted later.
The returned Store is not yet initialised — call Init before use.
func (*Store) AppendEvent ¶
AppendEvent inserts an event into the append-only log. If ev.ID is empty a fresh ULID is allocated; if ev.Timestamp is zero, the current UTC time is used.
func (*Store) ArchiveEntity ¶
ArchiveEntity marks an entity as archived without deleting it.
func (*Store) DB ¶
DB returns the underlying *sql.DB. Intended for test code that needs to poke at the schema directly (e.g. asserting append-only triggers fire). Production code MUST go through the Store interface.
func (*Store) DissolveRelation ¶
DissolveRelation removes a relation row. v0.1 deletes outright; the canonical record lives in the events log.
func (*Store) GetEntity ¶
GetEntity returns the entity with the given (peer, id), or (nil, nil) if not found.
func (*Store) ListEvents ¶
func (s *Store) ListEvents(ctx context.Context, peerDID string, since, until time.Time) ([]*types.Event, error)
ListEvents returns events in [since, until], ascending by timestamp then ID. Zero values for since/until mean unbounded on that side.
func (*Store) QueryEntities ¶
func (s *Store) QueryEntities(ctx context.Context, peerDID string, q types.EntityQuery) ([]*types.Entity, error)
QueryEntities lists entities for a peer, optionally filtered by type and JSON field equality. Archived rows are excluded unless q.IncludeArchived is true. Default Limit is 50.
func (*Store) QueryRelations ¶
func (s *Store) QueryRelations(ctx context.Context, peerDID, from, to, relType string, limit int) ([]*types.Relation, error)
QueryRelations returns relations matching the given non-empty filters.
func (*Store) SemanticSearch ¶
func (s *Store) SemanticSearch(ctx context.Context, peerDID string, vector []float32, typeFilter string, limit int) ([]types.SemanticHit, error)
SemanticSearch returns the top-`limit` entities by cosine similarity to the given vector, restricted to the given peer (and optionally entity type). Returns an empty slice if vector is empty.
func (*Store) SubstringSearch ¶
func (s *Store) SubstringSearch(ctx context.Context, peerDID, query, typeFilter string, limit int) ([]types.SemanticHit, error)
SubstringSearch returns entities whose JSON data contains the given query substring. Score is always 1.0.
func (*Store) TimeTravelEntities ¶
func (s *Store) TimeTravelEntities(ctx context.Context, peerDID string, q types.EntityQuery, asOf time.Time) ([]*types.Entity, error)
TimeTravelEntities reconstructs entity state by folding the event log up to (and including) asOf, then applying the EntityQuery filters in Go. Intended for occasional historical queries — the spec marks this "use sparingly".
func (*Store) UpsertEmbedding ¶
func (s *Store) UpsertEmbedding(ctx context.Context, peerDID, entityID string, vector []float32, model string) error
UpsertEmbedding writes or replaces the embedding for an entity.
func (*Store) UpsertEntity ¶
UpsertEntity inserts or replaces an entity row.
Source Files