memory

package
v0.1.0-beta.7 Latest Latest
Warning

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

Go to latest
Published: Feb 23, 2026 License: AGPL-3.0 Imports: 56 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func BotIDFromContext

func BotIDFromContext(ctx context.Context) string

BotIDFromContext returns bot ID carried by WithBotID.

func WithBotID

func WithBotID(ctx context.Context, botID string) context.Context

WithBotID attaches bot ID to context so model selection can honor bot settings.

Types

type AddRequest

type AddRequest struct {
	Message          string         `json:"message,omitempty"`
	Messages         []Message      `json:"messages,omitempty"`
	BotID            string         `json:"bot_id,omitempty"`
	AgentID          string         `json:"agent_id,omitempty"`
	RunID            string         `json:"run_id,omitempty"`
	Metadata         map[string]any `json:"metadata,omitempty"`
	Filters          map[string]any `json:"filters,omitempty"`
	Infer            *bool          `json:"infer,omitempty"`
	EmbeddingEnabled *bool          `json:"embedding_enabled,omitempty"`
}

type BM25Indexer

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

func NewBM25Indexer

func NewBM25Indexer(log *slog.Logger) *BM25Indexer

func (*BM25Indexer) AddDocument

func (b *BM25Indexer) AddDocument(lang string, termFreq map[string]int, docLen int) (indices []uint32, values []float32)

func (*BM25Indexer) BuildQueryVector

func (b *BM25Indexer) BuildQueryVector(lang string, termFreq map[string]int) (indices []uint32, values []float32)

func (*BM25Indexer) RemoveDocument

func (b *BM25Indexer) RemoveDocument(lang string, termFreq map[string]int, docLen int)

func (*BM25Indexer) TermFrequencies

func (b *BM25Indexer) TermFrequencies(lang, text string) (map[string]int, int, error)

type CDFPoint

type CDFPoint struct {
	K          int     `json:"k"`          // rank position (1-based, sorted by value desc)
	Cumulative float64 `json:"cumulative"` // cumulative weight fraction [0.0, 1.0]
}

CDFPoint represents one point on the cumulative contribution curve.

type CandidateMemory

type CandidateMemory struct {
	ID        string         `json:"id"`
	Memory    string         `json:"memory"`
	CreatedAt string         `json:"created_at,omitempty"`
	Metadata  map[string]any `json:"metadata,omitempty"`
}

type CompactRequest

type CompactRequest struct {
	Memories    []CandidateMemory `json:"memories"`
	TargetCount int               `json:"target_count"`
	DecayDays   int               `json:"decay_days,omitempty"`
}

type CompactResponse

type CompactResponse struct {
	Facts []string `json:"facts"`
}

type CompactResult

type CompactResult struct {
	BeforeCount int          `json:"before_count"`
	AfterCount  int          `json:"after_count"`
	Ratio       float64      `json:"ratio"`
	Results     []MemoryItem `json:"results"`
}

type DecideRequest

type DecideRequest struct {
	Facts      []string          `json:"facts"`
	Candidates []CandidateMemory `json:"candidates"`
	Filters    map[string]any    `json:"filters,omitempty"`
	Metadata   map[string]any    `json:"metadata,omitempty"`
}

type DecideResponse

type DecideResponse struct {
	Actions []DecisionAction `json:"actions"`
}

type DecisionAction

type DecisionAction struct {
	Event     string `json:"event"`
	ID        string `json:"id,omitempty"`
	Text      string `json:"text"`
	OldMemory string `json:"old_memory,omitempty"`
}

type DeleteAllRequest

type DeleteAllRequest struct {
	BotID   string         `json:"bot_id,omitempty"`
	AgentID string         `json:"agent_id,omitempty"`
	RunID   string         `json:"run_id,omitempty"`
	Filters map[string]any `json:"filters,omitempty"`
}

type DeleteResponse

type DeleteResponse struct {
	Message string `json:"message"`
}

type EmbedInput

type EmbedInput struct {
	Text     string `json:"text,omitempty"`
	ImageURL string `json:"image_url,omitempty"`
	VideoURL string `json:"video_url,omitempty"`
}

type EmbedUpsertRequest

type EmbedUpsertRequest struct {
	Type     string         `json:"type"`
	Provider string         `json:"provider,omitempty"`
	Model    string         `json:"model,omitempty"`
	Input    EmbedInput     `json:"input"`
	Source   string         `json:"source,omitempty"`
	BotID    string         `json:"bot_id,omitempty"`
	AgentID  string         `json:"agent_id,omitempty"`
	RunID    string         `json:"run_id,omitempty"`
	Metadata map[string]any `json:"metadata,omitempty"`
	Filters  map[string]any `json:"filters,omitempty"`
}

type EmbedUpsertResponse

type EmbedUpsertResponse struct {
	Item       MemoryItem `json:"item"`
	Provider   string     `json:"provider"`
	Model      string     `json:"model"`
	Dimensions int        `json:"dimensions"`
}

type ExtractRequest

type ExtractRequest struct {
	Messages []Message      `json:"messages"`
	Filters  map[string]any `json:"filters,omitempty"`
	Metadata map[string]any `json:"metadata,omitempty"`
}

type ExtractResponse

type ExtractResponse struct {
	Facts []string `json:"facts"`
}

type GetAllRequest

type GetAllRequest struct {
	BotID   string         `json:"bot_id,omitempty"`
	AgentID string         `json:"agent_id,omitempty"`
	RunID   string         `json:"run_id,omitempty"`
	Limit   int            `json:"limit,omitempty"`
	Filters map[string]any `json:"filters,omitempty"`
	NoStats bool           `json:"no_stats,omitempty"`
}

type LLM

type LLM interface {
	Extract(ctx context.Context, req ExtractRequest) (ExtractResponse, error)
	Decide(ctx context.Context, req DecideRequest) (DecideResponse, error)
	Compact(ctx context.Context, req CompactRequest) (CompactResponse, error)
	DetectLanguage(ctx context.Context, text string) (string, error)
}

LLM is the interface for LLM operations needed by memory service

type LLMClient

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

func NewLLMClient

func NewLLMClient(log *slog.Logger, baseURL, apiKey, model string, timeout time.Duration) (*LLMClient, error)

func (*LLMClient) Compact

func (c *LLMClient) Compact(ctx context.Context, req CompactRequest) (CompactResponse, error)

func (*LLMClient) Decide

func (c *LLMClient) Decide(ctx context.Context, req DecideRequest) (DecideResponse, error)

func (*LLMClient) DetectLanguage

func (c *LLMClient) DetectLanguage(ctx context.Context, text string) (string, error)

func (*LLMClient) Extract

func (c *LLMClient) Extract(ctx context.Context, req ExtractRequest) (ExtractResponse, error)

type Manifest

type Manifest struct {
	Version   int                      `json:"version"`
	UpdatedAt string                   `json:"updated_at"`
	Entries   map[string]ManifestEntry `json:"entries"`
}

Manifest is the index file that records everything needed to rebuild memories.

type ManifestEntry

type ManifestEntry struct {
	Hash      string         `json:"hash"`
	CreatedAt string         `json:"created_at"`
	Lang      string         `json:"lang,omitempty"`
	Filters   map[string]any `json:"filters,omitempty"`
}

ManifestEntry records metadata for a single memory entry.

type MemoryFS

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

MemoryFS persists memory entries as files inside the bot container via ExecRunner.

func NewMemoryFS

func NewMemoryFS(log *slog.Logger, runner container.ExecRunner, workDir string) *MemoryFS

NewMemoryFS creates a MemoryFS that writes through the given ExecRunner.

func (*MemoryFS) PersistMemories

func (fs *MemoryFS) PersistMemories(ctx context.Context, botID string, items []MemoryItem, filters map[string]any) error

PersistMemories writes .md files for new items and incrementally updates the manifest. Used after Add — does NOT delete existing files.

func (*MemoryFS) ReadAllMemoryFiles

func (fs *MemoryFS) ReadAllMemoryFiles(ctx context.Context, botID string) ([]MemoryItem, error)

ReadAllMemoryFiles lists and reads all .md files under memory/ and parses their frontmatter.

func (*MemoryFS) ReadManifest

func (fs *MemoryFS) ReadManifest(ctx context.Context, botID string) (*Manifest, error)

ReadManifest reads and parses the manifest.json file.

func (*MemoryFS) RebuildFiles

func (fs *MemoryFS) RebuildFiles(ctx context.Context, botID string, items []MemoryItem, filters map[string]any) error

RebuildFiles does a full replace: deletes all old memory/*.md files, writes new ones, and rewrites manifest from scratch. Used after Compact.

func (*MemoryFS) RemoveAllMemories

func (fs *MemoryFS) RemoveAllMemories(ctx context.Context, botID string) error

RemoveAllMemories deletes all memory files and the manifest.

func (*MemoryFS) RemoveMemories

func (fs *MemoryFS) RemoveMemories(ctx context.Context, botID string, ids []string) error

RemoveMemories removes specific memory files from the FS and updates the manifest.

type MemoryItem

type MemoryItem struct {
	ID          string         `json:"id"`
	Memory      string         `json:"memory"`
	Hash        string         `json:"hash,omitempty"`
	CreatedAt   string         `json:"created_at,omitempty"`
	UpdatedAt   string         `json:"updated_at,omitempty"`
	Score       float64        `json:"score,omitempty"`
	Metadata    map[string]any `json:"metadata,omitempty"`
	BotID       string         `json:"bot_id,omitempty"`
	AgentID     string         `json:"agent_id,omitempty"`
	RunID       string         `json:"run_id,omitempty"`
	TopKBuckets []TopKBucket   `json:"top_k_buckets,omitempty"`
	CDFCurve    []CDFPoint     `json:"cdf_curve,omitempty"`
}

type Message

type Message struct {
	Role    string `json:"role"`
	Content string `json:"content"`
}

type QdrantStore

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

func NewQdrantStore

func NewQdrantStore(log *slog.Logger, baseURL, apiKey, collection string, dimension int, sparseVectorName string, timeout time.Duration) (*QdrantStore, error)

func NewQdrantStoreWithVectors

func NewQdrantStoreWithVectors(log *slog.Logger, baseURL, apiKey, collection string, vectors map[string]int, sparseVectorName string, timeout time.Duration) (*QdrantStore, error)

func (*QdrantStore) Count

func (s *QdrantStore) Count(ctx context.Context, filters map[string]any) (uint64, error)

func (*QdrantStore) Delete

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

func (*QdrantStore) DeleteAll

func (s *QdrantStore) DeleteAll(ctx context.Context, filters map[string]any) error

func (*QdrantStore) DeleteBatch

func (s *QdrantStore) DeleteBatch(ctx context.Context, ids []string) error

func (*QdrantStore) Get

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

func (*QdrantStore) List

func (s *QdrantStore) List(ctx context.Context, limit int, filters map[string]any, withSparseVectors bool) ([]qdrantPoint, error)

func (*QdrantStore) NewSibling

func (s *QdrantStore) NewSibling(collection string, dimension int) (*QdrantStore, error)

func (*QdrantStore) Scroll

func (s *QdrantStore) Scroll(ctx context.Context, limit int, filters map[string]any, offset *qdrant.PointId) ([]qdrantPoint, *qdrant.PointId, error)

func (*QdrantStore) Search

func (s *QdrantStore) Search(ctx context.Context, vector []float32, limit int, filters map[string]any, vectorName string) ([]qdrantPoint, []float64, error)

func (*QdrantStore) SearchBySources

func (s *QdrantStore) SearchBySources(ctx context.Context, vector []float32, limit int, filters map[string]any, sources []string, vectorName string) (map[string][]qdrantPoint, map[string][]float64, error)

func (*QdrantStore) SearchSparse

func (s *QdrantStore) SearchSparse(ctx context.Context, indices []uint32, values []float32, limit int, filters map[string]any, withSparseVectors bool) ([]qdrantPoint, []float64, error)

func (*QdrantStore) SearchSparseBySources

func (s *QdrantStore) SearchSparseBySources(ctx context.Context, indices []uint32, values []float32, limit int, filters map[string]any, sources []string, withSparseVectors bool) (map[string][]qdrantPoint, map[string][]float64, error)

func (*QdrantStore) Upsert

func (s *QdrantStore) Upsert(ctx context.Context, points []qdrantPoint) error

type RebuildResult

type RebuildResult struct {
	FsCount       int `json:"fs_count"`
	QdrantCount   int `json:"qdrant_count"`
	MissingCount  int `json:"missing_count"`
	RestoredCount int `json:"restored_count"`
}

type SearchRequest

type SearchRequest struct {
	Query            string         `json:"query"`
	BotID            string         `json:"bot_id,omitempty"`
	AgentID          string         `json:"agent_id,omitempty"`
	RunID            string         `json:"run_id,omitempty"`
	Limit            int            `json:"limit,omitempty"`
	Filters          map[string]any `json:"filters,omitempty"`
	Sources          []string       `json:"sources,omitempty"`
	EmbeddingEnabled *bool          `json:"embedding_enabled,omitempty"`
	NoStats          bool           `json:"no_stats,omitempty"`
}

type SearchResponse

type SearchResponse struct {
	Results   []MemoryItem `json:"results"`
	Relations []any        `json:"relations,omitempty"`
}

type Service

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

func NewService

func NewService(log *slog.Logger, llm LLM, embedder embeddings.Embedder, store *QdrantStore, resolver *embeddings.Resolver, bm25 *BM25Indexer, defaultTextModelID, defaultMultimodalModelID string) *Service

func (*Service) Add

func (s *Service) Add(ctx context.Context, req AddRequest) (SearchResponse, error)

func (*Service) Compact

func (s *Service) Compact(ctx context.Context, filters map[string]any, ratio float64, decayDays int) (CompactResult, error)

func (*Service) Delete

func (s *Service) Delete(ctx context.Context, memoryID string) (DeleteResponse, error)

func (*Service) DeleteAll

func (s *Service) DeleteAll(ctx context.Context, req DeleteAllRequest) (DeleteResponse, error)

func (*Service) DeleteBatch

func (s *Service) DeleteBatch(ctx context.Context, memoryIDs []string) (DeleteResponse, error)

func (*Service) EmbedUpsert

func (s *Service) EmbedUpsert(ctx context.Context, req EmbedUpsertRequest) (EmbedUpsertResponse, error)

func (*Service) Get

func (s *Service) Get(ctx context.Context, memoryID string) (MemoryItem, error)

func (*Service) GetAll

func (s *Service) GetAll(ctx context.Context, req GetAllRequest) (SearchResponse, error)

func (*Service) RebuildAdd

func (s *Service) RebuildAdd(ctx context.Context, id, text string, filters map[string]any) (MemoryItem, error)

RebuildAdd inserts a memory with a specific ID (from filesystem recovery). Like applyAdd but preserves the given ID instead of generating a new UUID.

func (*Service) Search

func (s *Service) Search(ctx context.Context, req SearchRequest) (SearchResponse, error)

func (*Service) Update

func (s *Service) Update(ctx context.Context, req UpdateRequest) (MemoryItem, error)

func (*Service) Usage

func (s *Service) Usage(ctx context.Context, filters map[string]any) (UsageResponse, error)

func (*Service) WarmupBM25

func (s *Service) WarmupBM25(ctx context.Context, batchSize int) error

type TopKBucket

type TopKBucket struct {
	Index uint32  `json:"index"` // sparse dimension index (term hash)
	Value float32 `json:"value"` // weight (term frequency)
}

TopKBucket represents one bar in the Top-K sparse dimension bar chart.

type UpdateRequest

type UpdateRequest struct {
	MemoryID         string `json:"memory_id"`
	Memory           string `json:"memory"`
	EmbeddingEnabled *bool  `json:"embedding_enabled,omitempty"`
}

type UsageResponse

type UsageResponse struct {
	Count                 int   `json:"count"`
	TotalTextBytes        int64 `json:"total_text_bytes"`
	AvgTextBytes          int64 `json:"avg_text_bytes"`
	EstimatedStorageBytes int64 `json:"estimated_storage_bytes"`
}

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL