memory

package
v0.0.0-...-7a041ca Latest Latest
Warning

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

 Go to latest Published: Mar 9, 2026 License: MIT Imports: 17 Imported by: 0

Documentation

Index

Constants

View Source 
const ErrReadOnlySlice = memoryError("cannot write to a read-only memory slice")

Variables

This section is empty.

Functions

func CosineSimilarity 

func CosineSimilarity(a, b []float32) (float32, error)

CosineSimilarity calculates the cosine similarity between two float slices. Returns a value between -1.0 and 1.0 (closer to 1.0 means higher similarity).

func FormatHistory 

func FormatHistory(thread *ConversationThread, maxMessages int) string

FormatHistory converts a conversation thread's recent messages into a string suitable for injecting into an LLM prompt as conversation context.

Types

type ChromaStore 

type ChromaStore struct {
	BaseURL        string
	CollectionName string
	CollectionID   string

	Timeout time.Duration
	// contains filtered or unexported fields
}

ChromaStore is a persistent implementation of the Store interface for ChromaDB. It uses the ChromaDB REST API for operations.

func NewChromaStore 

func NewChromaStore(baseURL, collectionName string, timeout time.Duration) (*ChromaStore, error)

NewChromaStore initializes a new ChromaDB store with configurable timeout.

func (*ChromaStore) Add 

func (s *ChromaStore) Add(ctx context.Context, item *MemoryItem) error

func (*ChromaStore) BulkAdd 

func (s *ChromaStore) BulkAdd(ctx context.Context, items []*MemoryItem) error

BulkAdd inserts multiple items by calling Add for each.

func (*ChromaStore) Close 

func (s *ChromaStore) Close() error

func (*ChromaStore) Count 

func (s *ChromaStore) Count(ctx context.Context) (int, error)

Count returns the number of items in the collection.

func (*ChromaStore) Delete 

func (s *ChromaStore) Delete(ctx context.Context, id string) error

Delete removes an item from the collection by ID.

func (*ChromaStore) Reset 

func (s *ChromaStore) Reset(ctx context.Context) error

Reset clears all data by deleting and recreating the collection.

func (*ChromaStore) Search 

func (s *ChromaStore) Search(ctx context.Context, queryVector []float32, limit int) ([]*MemoryItem, error)

type ConversationMessage 

type ConversationMessage struct {
	ID        string                 `json:"id"`
	ThreadID  string                 `json:"thread_id"`
	Role      Role                   `json:"role"`
	Content   string                 `json:"content"`
	Metadata  map[string]interface{} `json:"metadata,omitempty"`
	CreatedAt time.Time              `json:"created_at"`
}

ConversationMessage represents a single message in a conversation thread.

type ConversationStore 

type ConversationStore interface {
	// CreateThread starts a new conversation thread.
	CreateThread(ctx context.Context, thread *ConversationThread) error

	// AddMessage appends a message to an existing thread.
	AddMessage(ctx context.Context, threadID string, msg ConversationMessage) error

	// GetThread retrieves a full conversation thread with all messages.
	GetThread(ctx context.Context, threadID string) (*ConversationThread, error)

	// GetMessages returns the last N messages from a thread (most recent first).
	GetMessages(ctx context.Context, threadID string, limit int) ([]ConversationMessage, error)

	// ListThreads returns all thread IDs and titles.
	ListThreads(ctx context.Context) ([]*ConversationThread, error)

	// DeleteThread removes a thread and all its messages.
	DeleteThread(ctx context.Context, threadID string) error
}

ConversationStore manages multi-turn conversation threads.

type ConversationThread 

type ConversationThread struct {
	ID        string                 `json:"id"`
	Title     string                 `json:"title,omitempty"`
	AgentRole string                 `json:"agent_role,omitempty"`
	Messages  []ConversationMessage  `json:"messages"`
	Metadata  map[string]interface{} `json:"metadata,omitempty"`
	CreatedAt time.Time              `json:"created_at"`
	UpdatedAt time.Time              `json:"updated_at"`
}

ConversationThread holds an ordered sequence of messages.

type Entity 

type Entity struct {
	Name        string
	Value       string
	Description string
}

Entity represents a tracked metadata object (e.g., "Project name", "User's tech stack").

type EntityStore 

type EntityStore interface {
	Upsert(ctx context.Context, name, value, description string) error
	Get(ctx context.Context, name string) (*Entity, error)
	Search(ctx context.Context, query string, limit int) ([]*MemoryItem, error)
}

EntityStore provides a structured way to manage named entities found during execution.

type InMemConversationStore 

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

InMemConversationStore implements ConversationStore with an in-memory map. Suitable for development, single-crew runs, and testing.

func NewInMemConversationStore 

func NewInMemConversationStore() *InMemConversationStore

NewInMemConversationStore creates an empty conversation store.

func (*InMemConversationStore) AddMessage 

func (s *InMemConversationStore) AddMessage(ctx context.Context, threadID string, msg ConversationMessage) error

func (*InMemConversationStore) CreateThread 

func (s *InMemConversationStore) CreateThread(ctx context.Context, thread *ConversationThread) error

func (*InMemConversationStore) DeleteThread 

func (s *InMemConversationStore) DeleteThread(ctx context.Context, threadID string) error

func (*InMemConversationStore) GetMessages 

func (s *InMemConversationStore) GetMessages(ctx context.Context, threadID string, limit int) ([]ConversationMessage, error)

func (*InMemConversationStore) GetThread 

func (s *InMemConversationStore) GetThread(ctx context.Context, threadID string) (*ConversationThread, error)

func (*InMemConversationStore) ListThreads 

func (s *InMemConversationStore) ListThreads(ctx context.Context) ([]*ConversationThread, error)

type InMemCosineStore 

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

InMemCosineStore is a basic reference implementation of `Store`. It acts as the default ShortTerm memory, keeping vectors in standard RAM slices and checking distances.

func NewInMemCosineStore 

func NewInMemCosineStore() *InMemCosineStore

func (*InMemCosineStore) Add 

func (s *InMemCosineStore) Add(ctx context.Context, item *MemoryItem) error

Add appends the memory item locally.

func (*InMemCosineStore) BulkAdd 

func (s *InMemCosineStore) BulkAdd(ctx context.Context, items []*MemoryItem) error

BulkAdd inserts multiple items.

func (*InMemCosineStore) Close 

func (s *InMemCosineStore) Close() error

Close is a no-op for in-memory stores.

func (*InMemCosineStore) Count 

func (s *InMemCosineStore) Count(ctx context.Context) (int, error)

Count returns the number of stored items.

func (*InMemCosineStore) Delete 

func (s *InMemCosineStore) Delete(ctx context.Context, id string) error

Delete removes an item by ID.

func (*InMemCosineStore) Reset 

func (s *InMemCosineStore) Reset(ctx context.Context) error

Reset clears all items from the store.

func (*InMemCosineStore) Search 

func (s *InMemCosineStore) Search(ctx context.Context, queryVector []float32, limit int) ([]*MemoryItem, error)

Search calculates cosine similarity against the entire memory graph and sorts the hits.

type InMemEntityStore 

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

InMemEntityStore is a simple map-based implementation of EntityStore.

func NewInMemEntityStore 

func NewInMemEntityStore() *InMemEntityStore

func (*InMemEntityStore) Add 

func (s *InMemEntityStore) Add(ctx context.Context, item *MemoryItem) error

func (*InMemEntityStore) Get 

func (s *InMemEntityStore) Get(ctx context.Context, name string) (*Entity, error)

func (*InMemEntityStore) Search 

func (s *InMemEntityStore) Search(ctx context.Context, query string, limit int) ([]*MemoryItem, error)

func (*InMemEntityStore) Upsert 

func (s *InMemEntityStore) Upsert(ctx context.Context, name, value, description string) error

type KnowledgeSource 

type KnowledgeSource interface {
	Query(ctx context.Context, query string) (string, error)
}

KnowledgeSource defines the interface for external knowledge retrieval.

type LongTermMemory 

type LongTermMemory struct {
	Store    Store
	Embedder llm.Client // Used to generate vectors for searches
}

LongTermMemory handles cross-execution persistent memory. It uses a vector-backed store for semantic retrieval.

func NewLongTermMemory 

func NewLongTermMemory(store Store, embedder llm.Client) *LongTermMemory

func (*LongTermMemory) Save 

func (l *LongTermMemory) Save(ctx context.Context, text string, metadata map[string]interface{}) error

func (*LongTermMemory) Search 

func (l *LongTermMemory) Search(ctx context.Context, query string, limit int) ([]*MemoryItem, error)

type Manager 

type Manager interface {
	Save(ctx context.Context, record MemoryRecord) error
	Search(ctx context.Context, query string, limit int) ([]MemoryRecord, error)
	Delete(ctx context.Context, id string) error
}

Manager defines the interface handling contextual info (UnifiedMemory).

type MemoryItem 

type MemoryItem struct {
	ID        string                 `json:"id"`
	Text      string                 `json:"text"`
	Vector    []float32              `json:"vector,omitempty"`
	Metadata  map[string]interface{} `json:"metadata,omitempty"`
	CreatedAt time.Time              `json:"created_at,omitempty"`
	ExpiresAt time.Time              `json:"expires_at,omitempty"` // zero = never expires
}

MemoryItem represents a single contextual block of agent interaction data.

func (*MemoryItem) Expired 

func (m *MemoryItem) Expired() bool

Expired returns true if the item has a TTL and it has passed.

type MemoryRecord 

type MemoryRecord struct {
	ID       string                 `json:"id"`
	Content  string                 `json:"content"`
	Metadata map[string]interface{} `json:"metadata"`
}

MemoryRecord represents a single unit of saved memory.

type MemoryScope 

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

MemoryScope restricts all memory operations to a single hierarchical subtree. Scopes use path-like notation: "/project/alpha", "/agent/researcher".

func (*MemoryScope) Forget 

func (ms *MemoryScope) Forget(ctx context.Context) error

Forget deletes all memories within this scope.

func (*MemoryScope) Path 

func (ms *MemoryScope) Path() string

Path returns the scope's hierarchical path.

func (*MemoryScope) Recall 

func (ms *MemoryScope) Recall(ctx context.Context, query string, opts *RecallOptions) ([]ScoredMemory, error)

Recall retrieves memories from within this scope only.

func (*MemoryScope) Remember 

func (ms *MemoryScope) Remember(ctx context.Context, content string, opts *RememberOptions) error

Remember stores a memory within this scope.

type MemorySlice 

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

MemorySlice provides a view across multiple disjoint scopes.

func (*MemorySlice) Recall 

func (ms *MemorySlice) Recall(ctx context.Context, query string, opts *RecallOptions) ([]ScoredMemory, error)

Recall retrieves memories from all scopes in the slice and merges results.

func (*MemorySlice) Remember 

func (ms *MemorySlice) Remember(ctx context.Context, content string, opts *RememberOptions) error

Remember stores a memory in the first scope of the slice.

type PineconeStore 

type PineconeStore struct {
	Host      string // Full index host URL
	APIKey    string
	Namespace string
	// contains filtered or unexported fields
}

--------------------------------------------------------------------------- PineconeStore — Pinecone Vector Database Client ---------------------------------------------------------------------------

Pinecone is a managed vector database optimized for similarity search at scale. It uses serverless or pod-based deployment.

Usage: 

store, err := memory.NewPineconeStore("https://index-xxx.svc.aped-xxx.pinecone.io", "your-api-key", "crew")
store.Add(ctx, item)
results, _ := store.Search(ctx, queryVector, 10)

func NewPineconeStore 

func NewPineconeStore(host, apiKey, namespace string) (*PineconeStore, error)

NewPineconeStore creates a client for a Pinecone index.

func (*PineconeStore) Add 

func (s *PineconeStore) Add(ctx context.Context, item *MemoryItem) error

func (*PineconeStore) BulkAdd 

func (s *PineconeStore) BulkAdd(ctx context.Context, items []*MemoryItem) error

func (*PineconeStore) Close 

func (s *PineconeStore) Close() error

func (*PineconeStore) Count 

func (s *PineconeStore) Count(ctx context.Context) (int, error)

func (*PineconeStore) Delete 

func (s *PineconeStore) Delete(ctx context.Context, id string) error

func (*PineconeStore) Reset 

func (s *PineconeStore) Reset(ctx context.Context) error

func (*PineconeStore) Search 

func (s *PineconeStore) Search(ctx context.Context, queryVector []float32, limit int) ([]*MemoryItem, error)

type QdrantStore 

type QdrantStore struct {
	BaseURL        string
	CollectionName string
	VectorSize     int
	// contains filtered or unexported fields
}

--------------------------------------------------------------------------- QdrantStore — Qdrant Vector Database Client ---------------------------------------------------------------------------

Qdrant is a high-performance vector similarity search engine with rich filtering, payload storage, and horizontal scaling.

Usage: 

store, err := memory.NewQdrantStore("http://localhost:6333", "crew_memory", 1536)
store.Add(ctx, item)
results, _ := store.Search(ctx, queryVector, 10)

func NewQdrantStore 

func NewQdrantStore(baseURL, collectionName string, vectorSize int) (*QdrantStore, error)

NewQdrantStore creates a client for a Qdrant collection. If the collection doesn't exist, it will be created with the given vector size.

func (*QdrantStore) Add 

func (s *QdrantStore) Add(ctx context.Context, item *MemoryItem) error

func (*QdrantStore) BulkAdd 

func (s *QdrantStore) BulkAdd(ctx context.Context, items []*MemoryItem) error

func (*QdrantStore) Close 

func (s *QdrantStore) Close() error

func (*QdrantStore) Count 

func (s *QdrantStore) Count(ctx context.Context) (int, error)

func (*QdrantStore) Delete 

func (s *QdrantStore) Delete(ctx context.Context, id string) error

func (*QdrantStore) Reset 

func (s *QdrantStore) Reset(ctx context.Context) error

func (*QdrantStore) Search 

func (s *QdrantStore) Search(ctx context.Context, queryVector []float32, limit int) ([]*MemoryItem, error)

type RecallDepth 

type RecallDepth string

RecallDepth controls how deep the recall search goes. 

const (
	RecallShallow RecallDepth = "shallow" // Direct vector search, no LLM
	RecallDeep    RecallDepth = "deep"    // Multi-step: query analysis, scope selection, parallel search
)

type RecallOptions 

type RecallOptions struct {
	Limit          int
	Depth          RecallDepth
	Scope          string
	Source         string
	IncludePrivate bool
}

RecallOptions provides optional parameters for Recall.

type RedisStore 

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

RedisStore is a scalable implementation of the Store interface using Redis.

func NewRedisStore 

func NewRedisStore(addrs []string, password string, db int, prefix string) (*RedisStore, error)

NewRedisStore initializes a new Redis client (Universal for Cluster/Sentinel support).

func (*RedisStore) Add 

func (s *RedisStore) Add(ctx context.Context, item *MemoryItem) error

func (*RedisStore) BulkAdd 

func (s *RedisStore) BulkAdd(ctx context.Context, items []*MemoryItem) error

BulkAdd inserts multiple items using a Redis pipeline for efficiency.

func (*RedisStore) Close 

func (s *RedisStore) Close() error

func (*RedisStore) Count 

func (s *RedisStore) Count(ctx context.Context) (int, error)

Count returns the total number of memory items.

func (*RedisStore) Delete 

func (s *RedisStore) Delete(ctx context.Context, id string) error

Delete removes a memory item by ID.

func (*RedisStore) Reset 

func (s *RedisStore) Reset(ctx context.Context) error

Reset clears all data by deleting all keys matching the prefix.

func (*RedisStore) Search 

func (s *RedisStore) Search(ctx context.Context, queryVector []float32, limit int) ([]*MemoryItem, error)

type RememberOptions 

type RememberOptions struct {
	Scope      string   // Hierarchical path (e.g., "/project/alpha")
	Source     string   // Provenance tracking (e.g., "user:alice")
	Private    bool     // Only visible when source matches
	Categories []string // Categorization tags
	Importance float64  // 0.0 to 1.0 (if 0, LLM infers it)
}

RememberOptions provides optional parameters for Remember.

type Role 

type Role string

Role represents a conversation participant. 

const (
	RoleUser      Role = "user"
	RoleAssistant Role = "assistant"
	RoleSystem    Role = "system"
	RoleTool      Role = "tool"
)

type SQLiteStore 

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

SQLiteStore is a persistent implementation of the Store interface using SQLite.

func NewSQLiteStore 

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

NewSQLiteStore initializes a new SQLite database for persistent memory.

func (*SQLiteStore) Add 

func (s *SQLiteStore) Add(ctx context.Context, item *MemoryItem) error

func (*SQLiteStore) BulkAdd 

func (s *SQLiteStore) BulkAdd(ctx context.Context, items []*MemoryItem) error

BulkAdd inserts multiple items in a single transaction.

func (*SQLiteStore) Close 

func (s *SQLiteStore) Close() error

func (*SQLiteStore) Count 

func (s *SQLiteStore) Count(ctx context.Context) (int, error)

Count returns the number of non-expired items.

func (*SQLiteStore) Delete 

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

Delete removes a memory item by ID.

func (*SQLiteStore) PurgeExpired 

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

PurgeExpired removes all items that have passed their TTL.

func (*SQLiteStore) Reset 

func (s *SQLiteStore) Reset(ctx context.Context) error

Reset clears all data by truncating the table.

func (*SQLiteStore) Search 

func (s *SQLiteStore) Search(ctx context.Context, queryVector []float32, limit int) ([]*MemoryItem, error)

type ScoredMemory 

type ScoredMemory struct {
	MemoryRecord
	Score      float64   `json:"score"`
	Similarity float64   `json:"similarity"`
	Recency    float64   `json:"recency"`
	Importance float64   `json:"importance"`
	CreatedAt  time.Time `json:"created_at"`
}

ScoredMemory is a memory record with its composite score attached.

type ShortTermMemory 

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

ShortTermMemory handles contextual, task-specific memory. It typically lasts for the duration of a single Crew execution.

func NewShortTermMemory 

func NewShortTermMemory() *ShortTermMemory

func (*ShortTermMemory) Add 

func (s *ShortTermMemory) Add(ctx context.Context, item *MemoryItem) error

func (*ShortTermMemory) Search 

func (s *ShortTermMemory) Search(ctx context.Context, query string, limit int) ([]*MemoryItem, error)

type SimpleKnowledgeSource 

type SimpleKnowledgeSource struct {
	Content string
}

SimpleKnowledgeSource is a text-based knowledge source.

func (*SimpleKnowledgeSource) Query 

func (s *SimpleKnowledgeSource) Query(ctx context.Context, query string) (string, error)

type Store 

type Store interface {
	// Add inserts a single item into the memory database.
	Add(ctx context.Context, item *MemoryItem) error

	// BulkAdd inserts multiple items in a single batch operation.
	BulkAdd(ctx context.Context, items []*MemoryItem) error

	// Delete removes an item by ID.
	Delete(ctx context.Context, id string) error

	// Search locates the nearest matching MemoryItems to a given query vector.
	Search(ctx context.Context, queryVector []float32, limit int) ([]*MemoryItem, error)

	// Count returns the total number of stored items.
	Count(ctx context.Context) (int, error)

	// Reset clears all data in the store.
	Reset(ctx context.Context) error
}

Store defines the interface for underlying memory backends.

type UnifiedMemory 

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

UnifiedMemory provides Remember/Recall/Forget API with composite scoring.

func NewUnifiedMemory 

func NewUnifiedMemory(store Store, llmClient llm.Client, cfg *UnifiedMemoryConfig) *UnifiedMemory

NewUnifiedMemory creates a new UnifiedMemory with the given store and optional config.

func (*UnifiedMemory) Close 

func (um *UnifiedMemory) Close()

Close drains writes and shuts down the background pool.

func (*UnifiedMemory) DrainWrites 

func (um *UnifiedMemory) DrainWrites()

DrainWrites waits for all pending background saves to complete.

func (*UnifiedMemory) ExtractMemories 

func (um *UnifiedMemory) ExtractMemories(ctx context.Context, content string) ([]string, error)

ExtractMemories breaks raw text into discrete atomic facts using LLM.

func (*UnifiedMemory) Forget 

func (um *UnifiedMemory) Forget(ctx context.Context, scope string) error

Forget deletes all memories under a specific scope.

func (*UnifiedMemory) Recall 

func (um *UnifiedMemory) Recall(ctx context.Context, query string, opts *RecallOptions) ([]ScoredMemory, error)

Recall retrieves memories ranked by composite score.

func (*UnifiedMemory) Remember 

func (um *UnifiedMemory) Remember(ctx context.Context, content string, opts *RememberOptions) error

Remember stores a memory with optional scope, source, and importance.

func (*UnifiedMemory) RememberMany 

func (um *UnifiedMemory) RememberMany(ctx context.Context, contents []string)

RememberMany stores multiple memories asynchronously with intra-batch dedup.

func (*UnifiedMemory) Scope 

func (um *UnifiedMemory) Scope(path string) *MemoryScope

Scope creates a MemoryScope restricted to the given hierarchical path.

func (*UnifiedMemory) Slice 

func (um *UnifiedMemory) Slice(scopes []string, readOnly bool) *MemorySlice

Slice creates a MemorySlice across the given scopes.

type UnifiedMemoryConfig 

type UnifiedMemoryConfig struct {
	RecencyWeight          float64 // Weight for recency in composite scoring (default: 0.3)
	SemanticWeight         float64 // Weight for semantic similarity (default: 0.5)
	ImportanceWeight       float64 // Weight for importance (default: 0.2)
	RecencyHalfLifeDays    int     // Days until recency score decays to 0.5 (default: 7)
	ConsolidationThreshold float64 // Similarity threshold for dedup (default: 0.85)
	BatchDedupThreshold    float64 // Cosine threshold for intra-batch dedup (default: 0.98)
	QueryAnalysisThreshold int     // Char length below which LLM analysis is skipped (default: 200)
}

UnifiedMemoryConfig configures the unified memory scoring and behavior.

type WeaviateStore 

type WeaviateStore struct {
	Host      string
	ClassName string // Weaviate class name (PascalCase required)
	APIKey    string // Optional — empty for local/anonymous
	// contains filtered or unexported fields
}

--------------------------------------------------------------------------- WeaviateStore — Weaviate Vector Database Client ---------------------------------------------------------------------------

Weaviate is an open-source vector database with built-in vectorization, hybrid search (vector + keyword), and GraphQL API.

Usage: 

store, err := memory.NewWeaviateStore("http://localhost:8080", "CrewMemory", "")
store.Add(ctx, item)
results, _ := store.Search(ctx, queryVector, 10)

func NewWeaviateStore 

func NewWeaviateStore(host, className, apiKey string) (*WeaviateStore, error)

NewWeaviateStore creates a client for a Weaviate class. If the class doesn't exist, it will be created.

func (*WeaviateStore) Add 

func (s *WeaviateStore) Add(ctx context.Context, item *MemoryItem) error

func (*WeaviateStore) BulkAdd 

func (s *WeaviateStore) BulkAdd(ctx context.Context, items []*MemoryItem) error

func (*WeaviateStore) Close 

func (s *WeaviateStore) Close() error

func (*WeaviateStore) Count 

func (s *WeaviateStore) Count(ctx context.Context) (int, error)

func (*WeaviateStore) Delete 

func (s *WeaviateStore) Delete(ctx context.Context, id string) error

func (*WeaviateStore) Reset 

func (s *WeaviateStore) Reset(ctx context.Context) error

func (*WeaviateStore) Search 

func (s *WeaviateStore) Search(ctx context.Context, queryVector []float32, limit int) ([]*MemoryItem, error)

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.