storage

package
v0.4.0 Latest Latest
Warning

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

 Go to latest Published: Jul 15, 2026 License: MIT Imports: 5 Imported by: 0

Documentation

Overview

Package storage defines the core persistence interfaces for Chronos.

Index

Constants

View Source 
const (
	// DefaultPageLimit is used when a caller passes a non-positive limit.
	DefaultPageLimit = 100
	// MaxPageLimit caps how many rows a single paged read may return.
	MaxPageLimit = 1000
)

Pagination bounds. Adapters clamp caller-supplied limits into this range so a single request can never scan an unbounded ledger.

Variables

This section is empty.

Functions

func ClampLimit added in v0.4.0 

func ClampLimit(limit int) int

ClampLimit normalizes a caller-supplied page limit into [1, MaxPageLimit], defaulting to DefaultPageLimit when limit <= 0.

func DecodeSeqCursor added in v0.4.0 

func DecodeSeqCursor(cursor string) (int64, error)

DecodeSeqCursor decodes a cursor produced by EncodeSeqCursor. An empty cursor decodes to 0 with no error.

func DecodeStrCursor added in v0.4.0 

func DecodeStrCursor(cursor string) (string, error)

DecodeStrCursor decodes a cursor produced by EncodeStrCursor. An empty cursor decodes to the empty string with no error.

func EncodeSeqCursor added in v0.4.0 

func EncodeSeqCursor(seq int64) string

EncodeSeqCursor encodes a monotonic sequence number into an opaque cursor.

func EncodeStrCursor added in v0.4.0 

func EncodeStrCursor(key string) string

EncodeStrCursor encodes a string key (e.g. a row's primary-key id) into an opaque cursor for keyset pagination.

Types

type AuditLog 

type AuditLog struct {
	ID        string         `json:"id"`
	SessionID string         `json:"session_id"`
	Actor     string         `json:"actor"`
	Action    string         `json:"action"`
	Resource  string         `json:"resource"`
	Detail    map[string]any `json:"detail,omitempty"`
	CreatedAt time.Time      `json:"created_at"`
}

AuditLog records a security-relevant event.

type BatchIngester added in v0.4.0 

type BatchIngester interface {
	// AppendEvents appends many ledger events atomically in one batch. Like
	// AppendEvent it is idempotent on the event id.
	AppendEvents(ctx context.Context, events []*Event) error
	// InsertTraces inserts many trace spans in one batch.
	InsertTraces(ctx context.Context, traces []*Trace) error
}

BatchIngester is an OPTIONAL interface a Storage adapter may implement to ingest many rows in a single round-trip (multi-row INSERT / COPY) instead of one statement per row. It is separate from Storage so that adding it never breaks existing implementations. Callers should type-assert: 

if b, ok := store.(storage.BatchIngester); ok {
	err := b.AppendEvents(ctx, events)
} else {
	for _, e := range events { _ = store.AppendEvent(ctx, e) }
}

type Checkpoint 

type Checkpoint struct {
	ID        string         `json:"id"`
	SessionID string         `json:"session_id"`
	RunID     string         `json:"run_id"`
	NodeID    string         `json:"node_id"`
	State     map[string]any `json:"state"`
	SeqNum    int64          `json:"seq_num"`
	CreatedAt time.Time      `json:"created_at"`
}

Checkpoint captures the full state of a run for resume/time-travel.

type CheckpointPage added in v0.4.0 

type CheckpointPage struct {
	Checkpoints []*Checkpoint `json:"checkpoints"`
	NextCursor  string        `json:"next_cursor,omitempty"`
}

CheckpointPage is a cursor-paginated slice of checkpoints.

type Config 

type Config struct {
	// Storage backend: "sqlite", "postgres", "mysql", "redis", "mongo", "dynamo"
	Backend string `json:"backend" yaml:"backend"`

	// DSN / connection string for the storage backend.
	DSN string `json:"dsn" yaml:"dsn"`

	// VectorBackend: "qdrant", "redisvector", "milvus", "weaviate", "pinecone"
	VectorBackend string `json:"vector_backend" yaml:"vector_backend"`

	// VectorDSN / connection for vector store.
	VectorDSN string `json:"vector_dsn" yaml:"vector_dsn"`
}

Config selects which storage and vector adapters to use at runtime.

type Embedding 

type Embedding struct {
	ID       string         `json:"id"`
	Vector   []float32      `json:"vector"`
	Metadata map[string]any `json:"metadata,omitempty"`
	Content  string         `json:"content,omitempty"`
}

Embedding represents a vector embedding with metadata.

type Event 

type Event struct {
	ID        string    `json:"id"`
	SessionID string    `json:"session_id"`
	SeqNum    int64     `json:"seq_num"`
	Type      string    `json:"type"`
	Payload   any       `json:"payload"`
	CreatedAt time.Time `json:"created_at"`
}

Event is an append-only ledger entry for replayability.

type EventPage added in v0.4.0 

type EventPage struct {
	Events     []*Event `json:"events"`
	NextCursor string   `json:"next_cursor,omitempty"`
}

EventPage is a cursor-paginated slice of events. NextCursor is empty when the page is the last one.

type MemoryRecord 

type MemoryRecord struct {
	ID        string    `json:"id"`
	SessionID string    `json:"session_id,omitempty"` // empty = long-term
	AgentID   string    `json:"agent_id"`
	UserID    string    `json:"user_id,omitempty"`
	Kind      string    `json:"kind"` // short_term, long_term
	Key       string    `json:"key"`
	Value     any       `json:"value"`
	CreatedAt time.Time `json:"created_at"`
}

MemoryRecord represents a short-term or long-term memory entry.

type Paginator added in v0.4.0 

type Paginator interface {
	ListEventsPaged(ctx context.Context, sessionID string, afterSeq int64, limit int, cursor string) (*EventPage, error)
	ListTracesPaged(ctx context.Context, sessionID string, limit int, cursor string) (*TracePage, error)
	ListCheckpointsPaged(ctx context.Context, sessionID string, limit int, cursor string) (*CheckpointPage, error)
}

Paginator is an OPTIONAL interface a Storage adapter may implement to expose cursor-paginated reads of the unbounded ledgers (traces, events, checkpoints).

It is deliberately separate from Storage so that adding it never breaks existing Storage implementations. Callers should type-assert: 

if p, ok := store.(storage.Paginator); ok {
	page, err := p.ListEventsPaged(ctx, sid, 0, 100, "")
}

Pass an empty cursor to fetch the first page; pass the previous page's NextCursor to fetch the following page. Limits are clamped via ClampLimit.

type Retention added in v0.4.0 

type Retention interface {
	// TrimEvents deletes events created strictly before olderThan.
	TrimEvents(ctx context.Context, olderThan time.Time) (int64, error)
	// TrimTraces deletes traces started strictly before olderThan.
	TrimTraces(ctx context.Context, olderThan time.Time) (int64, error)
	// TrimAuditLogs deletes audit logs created strictly before olderThan.
	TrimAuditLogs(ctx context.Context, olderThan time.Time) (int64, error)
	// TrimCheckpoints keeps only the most recent keep checkpoints (by seq_num)
	// for the given session and deletes the rest. keep <= 0 is a no-op.
	TrimCheckpoints(ctx context.Context, sessionID string, keep int) (int64, error)
}

Retention is an OPTIONAL interface a Storage adapter may implement to trim the unbounded, append-only tables (events, traces, audit logs, checkpoints). It is separate from Storage so that adding it never breaks existing implementations.

Each Trim* method returns the number of rows removed. Callers should type-assert: 

if r, ok := store.(storage.Retention); ok {
	_, _ = r.TrimEvents(ctx, time.Now().Add(-30*24*time.Hour))
}

type RetentionPolicy added in v0.4.0 

type RetentionPolicy struct {
	// MaxAge deletes events, traces and audit logs older than now-MaxAge.
	// Zero disables age-based trimming.
	MaxAge time.Duration `json:"max_age,omitempty"`
	// KeepCheckpointsPerSession limits checkpoints retained per session.
	// Zero disables checkpoint trimming.
	KeepCheckpointsPerSession int `json:"keep_checkpoints_per_session,omitempty"`
}

RetentionPolicy describes a time-and-count based retention window that a caller (e.g. a background job) can apply via ApplyRetention.

type RetentionResult added in v0.4.0 

type RetentionResult struct {
	Events      int64 `json:"events"`
	Traces      int64 `json:"traces"`
	AuditLogs   int64 `json:"audit_logs"`
	Checkpoints int64 `json:"checkpoints"`
}

RetentionResult reports how many rows each Trim* step removed.

func ApplyRetention added in v0.4.0 

func ApplyRetention(ctx context.Context, r Retention, policy RetentionPolicy, sessionIDs []string) (RetentionResult, error)

ApplyRetention runs a RetentionPolicy against a Retention store. The sessionIDs argument scopes checkpoint trimming (checkpoint retention is per-session); pass nil to skip checkpoint trimming.

type SearchResult 

type SearchResult struct {
	Embedding
	Score float32 `json:"score"`
}

SearchResult is a single result from a similarity search.

type Session 

type Session struct {
	ID        string         `json:"id"`
	AgentID   string         `json:"agent_id"`
	Status    string         `json:"status"` // running, paused, completed, failed
	Metadata  map[string]any `json:"metadata,omitempty"`
	CreatedAt time.Time      `json:"created_at"`
	UpdatedAt time.Time      `json:"updated_at"`
}

Session represents an agent execution session.

type Storage 

type Storage interface {
	// Sessions
	CreateSession(ctx context.Context, s *Session) error
	GetSession(ctx context.Context, id string) (*Session, error)
	UpdateSession(ctx context.Context, s *Session) error
	ListSessions(ctx context.Context, agentID string, limit, offset int) ([]*Session, error)

	// Memory
	PutMemory(ctx context.Context, m *MemoryRecord) error
	GetMemory(ctx context.Context, agentID, key string) (*MemoryRecord, error)
	ListMemory(ctx context.Context, agentID string, kind string) ([]*MemoryRecord, error)
	DeleteMemory(ctx context.Context, id string) error

	// Audit logs
	AppendAuditLog(ctx context.Context, log *AuditLog) error
	ListAuditLogs(ctx context.Context, sessionID string, limit, offset int) ([]*AuditLog, error)

	// Traces
	InsertTrace(ctx context.Context, t *Trace) error
	GetTrace(ctx context.Context, id string) (*Trace, error)
	ListTraces(ctx context.Context, sessionID string) ([]*Trace, error)

	// Event ledger (append-only)
	AppendEvent(ctx context.Context, e *Event) error
	ListEvents(ctx context.Context, sessionID string, afterSeq int64) ([]*Event, error)

	// Checkpoints
	SaveCheckpoint(ctx context.Context, cp *Checkpoint) error
	GetCheckpoint(ctx context.Context, id string) (*Checkpoint, error)
	GetLatestCheckpoint(ctx context.Context, sessionID string) (*Checkpoint, error)
	ListCheckpoints(ctx context.Context, sessionID string) ([]*Checkpoint, error)

	// Lifecycle
	Migrate(ctx context.Context) error
	Close() error
}

Storage is the primary persistence interface. All adapters must implement this.

type Trace 

type Trace struct {
	ID        string    `json:"id"`
	SessionID string    `json:"session_id"`
	ParentID  string    `json:"parent_id,omitempty"`
	Name      string    `json:"name"`
	Kind      string    `json:"kind"` // node, tool_call, model_call, approval
	Input     any       `json:"input,omitempty"`
	Output    any       `json:"output,omitempty"`
	Error     string    `json:"error,omitempty"`
	StartedAt time.Time `json:"started_at"`
	EndedAt   time.Time `json:"ended_at,omitempty"`
}

Trace represents a single trace span for observability.

type TracePage added in v0.4.0 

type TracePage struct {
	Traces     []*Trace `json:"traces"`
	NextCursor string   `json:"next_cursor,omitempty"`
}

TracePage is a cursor-paginated slice of traces.

type VectorStore 

type VectorStore interface {
	// Upsert inserts or updates embeddings in the given collection.
	Upsert(ctx context.Context, collection string, embeddings []Embedding) error

	// Search performs similarity search and returns top-k results.
	Search(ctx context.Context, collection string, query []float32, topK int) ([]SearchResult, error)

	// Delete removes embeddings by IDs.
	Delete(ctx context.Context, collection string, ids []string) error

	// CreateCollection ensures a collection exists.
	CreateCollection(ctx context.Context, name string, dimension int) error

	// Close releases resources.
	Close() error
}

VectorStore abstracts vector DB operations for RAG and embeddings.

Source Files

View all Source files

Directories

Path Synopsis
adapters
chromadb
Package chromadb provides a ChromaDB-backed VectorStore adapter for Chronos.
 Package chromadb provides a ChromaDB-backed VectorStore adapter for Chronos.
dynamo
Package dynamo provides a DynamoDB-backed Storage adapter for Chronos.
 Package dynamo provides a DynamoDB-backed Storage adapter for Chronos.
lancedb
Package lancedb provides a LanceDB-backed VectorStore adapter for Chronos.
 Package lancedb provides a LanceDB-backed VectorStore adapter for Chronos.
memory
Package memory provides an in-memory Storage adapter for Chronos.
 Package memory provides an in-memory Storage adapter for Chronos.
milvus
Package milvus provides a Milvus-backed VectorStore adapter for Chronos.
 Package milvus provides a Milvus-backed VectorStore adapter for Chronos.
mongo
Package mongo provides a MongoDB-backed Storage adapter for Chronos.
 Package mongo provides a MongoDB-backed Storage adapter for Chronos.
pgvector
Package pgvector provides a PostgreSQL+pgvector-backed VectorStore adapter for Chronos.
 Package pgvector provides a PostgreSQL+pgvector-backed VectorStore adapter for Chronos.
pinecone
Package pinecone provides a Pinecone-backed VectorStore adapter for Chronos.
 Package pinecone provides a Pinecone-backed VectorStore adapter for Chronos.
postgres
Package postgres provides a PostgreSQL-backed Storage adapter for Chronos.
 Package postgres provides a PostgreSQL-backed Storage adapter for Chronos.
qdrant
Package qdrant provides a Qdrant-backed VectorStore adapter for Chronos.
 Package qdrant provides a Qdrant-backed VectorStore adapter for Chronos.
redis
Package redis provides a Redis-backed Storage adapter for Chronos.
 Package redis provides a Redis-backed Storage adapter for Chronos.
redisvector
Package redisvector provides a Redis-backed VectorStore adapter using RediSearch.
 Package redisvector provides a Redis-backed VectorStore adapter using RediSearch.
sqlite
Package sqlite provides a SQLite-backed Storage adapter for Chronos.
 Package sqlite provides a SQLite-backed Storage adapter for Chronos.
weaviate
Package weaviate provides a Weaviate-backed VectorStore adapter for Chronos.
 Package weaviate provides a Weaviate-backed VectorStore adapter for Chronos.
Package migrate provides versioned database migrations for SQL backends.
 Package migrate provides versioned database migrations for SQL backends.

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.