memory

Documentation

Overview

Package memory provides long-term memory storage for AI agents using vector embeddings.

Memory allows agents to remember facts about users across conversations. Unlike sessions which store raw conversation history, memory stores semantic facts that can be retrieved using similarity search.

How Memory Works

When configured with AutoExtract, the agent automatically extracts important facts from conversations (e.g., "User's name is Alice", "User prefers Italian food"). These facts are stored as vector embeddings and retrieved when relevant to future conversations.

Built-in Stores

The package provides two built-in stores that require an embeddings client:

• NewStore: In-memory storage with vector search
• FileStore: File-based storage with vector search

For production use, see the memory/pgvector package for PostgreSQL with pgvector.

Usage with Agent

embedder := openai.NewEmbedding(
    openai.WithAPIKey(os.Getenv("OPENAI_API_KEY")),
    openai.WithModel(model.OpenAIEmbeddingModels[model.TextEmbedding3Small]),
)

store := memory.FileStore("./memories", embedder)

myAgent := agent.New(llmClient,
    agent.WithMemory("user-123", store,
        memory.AutoExtract(),
        memory.AutoDedup(),
    ),
)

Memory Options

• AutoExtract: Automatically extract facts from conversations
• AutoDedup: Deduplicate similar memories to avoid redundancy
• LLM: Use a separate LLM for memory operations (extraction/deduplication)

Custom Implementations

Implement the Store interface for custom vector databases like Qdrant, Pinecone, or Weaviate.

Index

• func ExtractFacts(ctx context.Context, llmClient llm.LLM, messages []message.Message) ([]string, error)
• func Tools(store Store, memoryID string) []tool.BaseTool
• type Config
  • func Apply(opts ...Option) *Config
• type DedupDecision
• type DedupEvent
• type DedupResult
  • func Deduplicate(ctx context.Context, llmClient llm.LLM, newFact string, existing []Entry) (*DedupResult, error)
• type Entry
• type IDGenerator
• type Option
  • func AutoDedup() Option
  • func AutoExtract() Option
  • func LLM(l llm.LLM) Option
• type Store
  • func FileStore(dir string, embedder embeddings.Embedding, opts ...StoreOption) Store
  • func NewStore(embedder embeddings.Embedding, opts ...StoreOption) Store
• type StoreOption
  • func WithIDGenerator(gen IDGenerator) StoreOption

Functions

func ExtractFacts

func ExtractFacts(
	ctx context.Context,
	llmClient llm.LLM,
	messages []message.Message,
) ([]string, error)

ExtractFacts extracts facts from a conversation using an LLM. It only extracts facts from user messages, ignoring system and assistant messages.

func Tools

func Tools(store Store, memoryID string) []tool.BaseTool

Tools returns a set of tools the LLM can use to manage memory directly: store_memory, recall_memories, replace_memory, delete_memory. The tools operate on the given Store under memoryID. Wire them into your agent when you want the LLM to control persistence explicitly (i.e., when auto-extraction is disabled).

Used by both agent.WithMemory and voice.WithMemory in their non-auto- extract modes.

Types

type Config

type Config struct {
	AutoExtract bool
	AutoDedup   bool
	LLM         llm.LLM
}

Config holds memory-related configuration for an agent.

func Apply

func Apply(opts ...Option) *Config

Apply applies all options to a Config and returns it.

type DedupDecision

type DedupDecision struct {
	Event    DedupEvent `json:"event"`
	MemoryID string     `json:"memory_id,omitempty"`
	Text     string     `json:"text"`
}

DedupDecision represents a single deduplication decision.

type DedupEvent

type DedupEvent string

DedupEvent represents the type of deduplication action to take.

const (
	DedupEventAdd    DedupEvent = "ADD"
	DedupEventUpdate DedupEvent = "UPDATE"
	DedupEventDelete DedupEvent = "DELETE"
	DedupEventNone   DedupEvent = "NONE"
)

Dedup event types.

type DedupResult

type DedupResult struct {
	Decisions []DedupDecision `json:"decisions"`
}

DedupResult contains all deduplication decisions for a fact.

func Deduplicate

func Deduplicate(
	ctx context.Context,
	llmClient llm.LLM,
	newFact string,
	existing []Entry,
) (*DedupResult, error)

Deduplicate checks if a new fact conflicts with or duplicates existing memories. It uses an LLM to decide whether to ADD, UPDATE, DELETE, or skip the new fact.

type Entry

type Entry struct {
	ID        string         `json:"id"`
	Content   string         `json:"content"`
	OwnerID   string         `json:"owner_id"`
	Score     float64        `json:"score"`
	CreatedAt time.Time      `json:"created_at"`
	Metadata  map[string]any `json:"metadata,omitempty"`
}

Entry represents a single memory entry.

type IDGenerator

type IDGenerator func() string

IDGenerator is a function that generates unique IDs for memory entries.

type Option

type Option func(*Config)

Option is a functional option for configuring memory behavior.

func AutoDedup

func AutoDedup() Option

AutoDedup enables LLM-based memory deduplication on store. When enabled, before storing a new memory, the agent searches for similar existing memories and asks an LLM to decide whether to ADD, UPDATE, DELETE, or skip.

func AutoExtract

func AutoExtract() Option

AutoExtract enables automatic fact extraction from conversations. When enabled, the agent uses an LLM to extract relevant facts from each conversation and stores them in the memory store.

func LLM

func LLM(l llm.LLM) Option

LLM sets a separate LLM for memory operations (extraction and deduplication). Useful for using a cheaper or faster model for background memory tasks while keeping the main conversation on a more capable model.

type Store

type Store interface {
	Store(
		ctx context.Context,
		id string,
		fact string,
		metadata map[string]any,
	) error
	Search(
		ctx context.Context,
		id string,
		query string,
		limit int,
	) ([]Entry, error)
	GetAll(ctx context.Context, id string, limit int) ([]Entry, error)
	Delete(ctx context.Context, memoryID string) error
	Update(
		ctx context.Context,
		memoryID string,
		fact string,
		metadata map[string]any,
	) error
}

Store is the interface for memory persistence. Users must implement this interface with their own vector store (e.g., pgvector, Qdrant, Pinecone) as memory requires embeddings for semantic search to work correctly.

func FileStore

func FileStore(
	dir string,
	embedder embeddings.Embedding,
	opts ...StoreOption,
) Store

FileStore creates a file-based Store that persists memories to disk. Each owner's memories are stored in a separate JSON file in the specified directory. The embedder is used for vector similarity search.

func NewStore

func NewStore(embedder embeddings.Embedding, opts ...StoreOption) Store

NewStore creates an in-memory Store that uses the provided embedder for vector similarity search. Data is not persisted and will be lost when the process exits.

type StoreOption

type StoreOption func(*storeConfig)

StoreOption configures a built-in memory store.

func WithIDGenerator

func WithIDGenerator(gen IDGenerator) StoreOption

WithIDGenerator sets a custom ID generator for the store. By default, UUIDs are used.