store

package
v0.2.11 Latest Latest
Warning

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

 Go to latest Published: Dec 23, 2025 License: MIT Imports: 6 Imported by: 0

Documentation

Overview

Package store provides pluggable state management for gains workflows and agents.

The package offers two main types:

  • Store: A generic key-value store with map[string]any semantics
  • MessageStore: A specialized store for conversation history

All types support pluggable persistence through the Adapter interface, with a default in-memory implementation provided via MemoryAdapter.

Basic Usage

Create a store with the default in-memory adapter: 

s := store.New(nil)
s.Set("name", "Alice")
s.Set("count", 42)

name := s.GetString("name")  // "Alice"
count := s.GetInt("count")   // 42

Message Store

Use MessageStore for conversation history: 

history := store.NewMessageStore(nil)
history.Append(gains.Message{Role: gains.RoleUser, Content: "Hello"})

msgs := history.Messages() // Get all messages

Persistence

Persist state by calling Sync, reload with Reload: 

s := store.New(myAdapter)
s.Set("key", "value")

// Persist to adapter
if err := s.Sync(ctx); err != nil {
    log.Fatal(err)
}

// Later, reload from adapter
if err := s.Reload(ctx); err != nil {
    log.Fatal(err)
}

Custom Adapters

Implement the Adapter interface for custom persistence: 

type RedisAdapter struct { ... }

func (r *RedisAdapter) Get(ctx context.Context, key string) (json.RawMessage, bool, error) { ... }
func (r *RedisAdapter) Set(ctx context.Context, key string, value json.RawMessage) error { ... }
// ... implement remaining methods

s := store.New(&RedisAdapter{})

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrKeyNotFound indicates the requested key does not exist.
	ErrKeyNotFound = errors.New("store: key not found")

	// ErrAdapterClosed indicates the adapter has been closed.
	ErrAdapterClosed = errors.New("store: adapter closed")
)

Functions

This section is empty.

Types

type Adapter 

type Adapter interface {
	// Get retrieves a value by key. Returns nil, false, nil if not found.
	Get(ctx context.Context, key string) (json.RawMessage, bool, error)

	// Set stores a value by key.
	Set(ctx context.Context, key string, value json.RawMessage) error

	// Delete removes a key. No error if key doesn't exist.
	Delete(ctx context.Context, key string) error

	// Has returns true if the key exists.
	Has(ctx context.Context, key string) (bool, error)

	// Keys returns all keys.
	Keys(ctx context.Context) ([]string, error)

	// Len returns the number of stored keys.
	Len(ctx context.Context) (int, error)

	// Clear removes all data.
	Clear(ctx context.Context) error

	// Load retrieves all data as a map.
	Load(ctx context.Context) (map[string]json.RawMessage, error)

	// Save stores all data from a map, replacing existing data.
	Save(ctx context.Context, data map[string]json.RawMessage) error
}

Adapter defines the interface for persistence backends. Implementations must be thread-safe.

type MemoryAdapter 

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

MemoryAdapter provides thread-safe in-memory storage.

func NewMemoryAdapter 

func NewMemoryAdapter() *MemoryAdapter

NewMemoryAdapter creates a new in-memory adapter.

func (*MemoryAdapter) Clear 

func (m *MemoryAdapter) Clear(_ context.Context) error

Clear removes all data.

func (*MemoryAdapter) Delete 

func (m *MemoryAdapter) Delete(_ context.Context, key string) error

Delete removes a key.

func (*MemoryAdapter) Get 

func (m *MemoryAdapter) Get(_ context.Context, key string) (json.RawMessage, bool, error)

Get retrieves a value by key.

func (*MemoryAdapter) Has 

func (m *MemoryAdapter) Has(_ context.Context, key string) (bool, error)

Has returns true if the key exists.

func (*MemoryAdapter) Keys 

func (m *MemoryAdapter) Keys(_ context.Context) ([]string, error)

Keys returns all keys.

func (*MemoryAdapter) Len 

func (m *MemoryAdapter) Len(_ context.Context) (int, error)

Len returns the number of stored keys.

func (*MemoryAdapter) Load 

func (m *MemoryAdapter) Load(_ context.Context) (map[string]json.RawMessage, error)

Load retrieves all data as a map.

func (*MemoryAdapter) Save 

func (m *MemoryAdapter) Save(_ context.Context, data map[string]json.RawMessage) error

Save stores all data from a map, replacing existing data.

func (*MemoryAdapter) Set 

func (m *MemoryAdapter) Set(_ context.Context, key string, value json.RawMessage) error

Set stores a value by key.

type MessageStore 

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

MessageStore manages conversation history with persistence support.

func NewMessageStore 

func NewMessageStore(adapter Adapter) *MessageStore

NewMessageStore creates a new MessageStore with the given adapter. If adapter is nil, a default in-memory adapter is used.

func NewMessageStoreFrom 

func NewMessageStoreFrom(messages []ai.Message, adapter Adapter) *MessageStore

NewMessageStoreFrom creates a MessageStore initialized with existing messages.

func (*MessageStore) Adapter 

func (m *MessageStore) Adapter() Adapter

Adapter returns the underlying adapter.

func (*MessageStore) Append 

func (m *MessageStore) Append(msgs ...ai.Message)

Append adds messages to the store.

func (*MessageStore) Clear 

func (m *MessageStore) Clear()

Clear removes all messages.

func (*MessageStore) Clone 

func (m *MessageStore) Clone() *MessageStore

Clone creates a deep copy of the MessageStore.

func (*MessageStore) Last 

func (m *MessageStore) Last(n int) []ai.Message

Last returns the last n messages. If n > Len(), returns all messages.

func (*MessageStore) Len 

func (m *MessageStore) Len() int

Len returns the number of messages.

func (*MessageStore) Messages 

func (m *MessageStore) Messages() []ai.Message

Messages returns a copy of all messages.

func (*MessageStore) Reload 

func (m *MessageStore) Reload(ctx context.Context, key string) error

Reload loads messages from the adapter using the given key.

func (*MessageStore) Sync 

func (m *MessageStore) Sync(ctx context.Context, key string) error

Sync persists the messages to the adapter under the given key.

type SerializationError 

type SerializationError struct {
	Key string
	Err error
}

SerializationError wraps JSON marshaling/unmarshaling errors with context.

func (*SerializationError) Error 

func (e *SerializationError) Error() string

func (*SerializationError) Unwrap 

func (e *SerializationError) Unwrap() error

type Store 

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

Store provides thread-safe key-value state management with pluggable persistence.

func New 

func New(adapter Adapter) *Store

New creates a new Store with the given adapter. If adapter is nil, a default in-memory adapter is used.

func NewFrom 

func NewFrom(data map[string]any) *Store

NewFrom creates a new Store initialized with the given data.

func (*Store) Adapter 

func (s *Store) Adapter() Adapter

Adapter returns the underlying adapter.

func (*Store) Clone 

func (s *Store) Clone() *Store

Clone creates a shallow copy of the store with a new in-memory adapter.

func (*Store) Data 

func (s *Store) Data() map[string]any

Data returns a shallow copy of the internal cache map.

func (*Store) Delete 

func (s *Store) Delete(key string)

Delete removes a key from the store.

func (*Store) Get 

func (s *Store) Get(key string) (any, bool)

Get retrieves a value from the store.

func (*Store) GetBool 

func (s *Store) GetBool(key string) bool

GetBool retrieves a bool value. Returns false if not found or wrong type.

func (*Store) GetFloat 

func (s *Store) GetFloat(key string) float64

GetFloat retrieves a float64 value. Returns 0.0 if not found or wrong type.

func (*Store) GetInt 

func (s *Store) GetInt(key string) int

GetInt retrieves an int value. Returns 0 if not found or wrong type. Handles float64 from JSON unmarshaling.

func (*Store) GetString 

func (s *Store) GetString(key string) string

GetString retrieves a string value. Returns empty string if not found or wrong type.

func (*Store) Has 

func (s *Store) Has(key string) bool

Has returns true if the key exists.

func (*Store) Keys 

func (s *Store) Keys() []string

Keys returns all keys in the store.

func (*Store) Len 

func (s *Store) Len() int

Len returns the number of keys in the store.

func (*Store) Merge 

func (s *Store) Merge(other *Store)

Merge copies values from another store, overwriting existing keys.

func (*Store) Reload 

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

Reload loads data from the adapter into the cache.

func (*Store) Set 

func (s *Store) Set(key string, value any)

Set stores a value in the store.

func (*Store) Sync 

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

Sync persists the current cache to the adapter.

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.