memoryrails

README

MemoryRails

Agent memory management for Go LLM applications. Pluggable embeddings + vector stores.

mgr := memoryrails.NewManager(embedder, store)

// Store a memory
mgr.Remember(ctx, "User prefers dark mode", memoryrails.TypeFact, nil)

// Recall relevant memories
results, _ := mgr.Recall(ctx, "What are the user's preferences?", memoryrails.RecallOptions{Limit: 5})

Install

go get github.com/promptrails/memoryrails

Features

• 5 memory types — conversation, fact, procedure, episodic, semantic
• 5 embedding providers — OpenAI, Ollama, Cohere, Gemini, Voyage AI
• Pluggable vector stores — in-memory (included), pgvector, SQLite, Qdrant
• Importance scoring — time-based decay + access frequency boost
• Semantic search — cosine similarity with configurable threshold
• Access tracking — automatic retrieval count and timestamp
• Framework independent — works with any Go LLM library

Embedding Providers

Provider	Package	Models
OpenAI	embedders/openai	text-embedding-3-small (1536d), text-embedding-3-large (3072d)
Ollama	embedders/ollama	nomic-embed-text, mxbai-embed-large, all-minilm
Cohere	embedders/cohere	embed-v4.0 (1024d)
Gemini	embedders/gemini	text-embedding-004 (768d)
Voyage AI	embedders/voyage	voyage-3 (1024d)

Vector Stores

Store	Package	Use Case
In-Memory	stores/inmemory	Development, testing, small scale (< 10K)
PostgreSQL + pgvector	stores/pgvector	Production, HNSW indexing, GORM
SQLite	stores/sqlite	Edge, CLI tools, single-machine
Qdrant	stores/qdrant	High-performance vector DB, REST API

Documentation

Getting Started	Installation and quick start
Embedders	Embedding provider configuration
Stores	Vector store backends
Scoring	Importance decay and retrieval ranking

Full docs: promptrails.github.io/memoryrails

Part of the PromptRails AI Toolkit

• LangRails — Unified LLM provider interface
• GuardRails — Content safety scanning
• MemoryRails — Agent memory management
• MediaRails — AI media generation

License

MIT — PromptRails

Documentation

Overview

Package memoryrails provides agent memory management for Go LLM applications.

It stores, embeds, and retrieves memories using pluggable embedding providers and vector stores. Supports 5 memory types, importance scoring with decay, and semantic similarity search.

Quick Start

mgr := memoryrails.NewManager(embedder, store)

// Store a memory
mem, _ := mgr.Remember(ctx, "The user prefers dark mode.", memoryrails.TypeFact, nil)

// Recall relevant memories
results, _ := mgr.Recall(ctx, "What are the user's preferences?", memoryrails.RecallOptions{Limit: 5})
for _, r := range results {
	fmt.Printf("%.2f: %s\n", r.Similarity, r.Memory.Content)
}

Index

• type Embedder
• type ListOptions
• type Manager
  • func NewManager(embedder Embedder, store Store, opts ...ManagerOption) *Manager
  • func (m *Manager) Forget(ctx context.Context, id string) error
  • func (m *Manager) Get(ctx context.Context, id string) (*Memory, error)
  • func (m *Manager) List(ctx context.Context, opts ListOptions) ([]*Memory, error)
  • func (m *Manager) Recall(ctx context.Context, query string, opts RecallOptions) ([]SearchResult, error)
  • func (m *Manager) Remember(ctx context.Context, content string, memType MemoryType, ...) (*Memory, error)
• type ManagerOption
  • func WithScorer(scorer Scorer) ManagerOption
• type Memory
• type MemoryType
• type RecallOptions
• type RememberOptions
• type Scorer
• type SearchOptions
• type SearchResult
• type Store

Types

type Embedder

type Embedder interface {
	// Embed generates a vector embedding for a single text.
	Embed(ctx context.Context, text string) ([]float64, error)

	// EmbedBatch generates embeddings for multiple texts.
	// Returns a slice of embeddings in the same order as the input.
	EmbedBatch(ctx context.Context, texts []string) ([][]float64, error)

	// Dimensions returns the dimensionality of the embedding vectors.
	Dimensions() int
}

Embedder generates vector embeddings from text. Implementations should be safe for concurrent use.

type ListOptions

type ListOptions struct {
	// Limit is the maximum number of results. Default: 50.
	Limit int

	// Offset is the number of results to skip.
	Offset int

	// Type filters results to a specific memory type. Empty = all types.
	Type MemoryType

	// OrderBy is the field to sort by. Default: "created_at".
	OrderBy string

	// Descending reverses the sort order.
	Descending bool
}

ListOptions configures a memory listing.

type Manager

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

Manager orchestrates embedding generation, storage, and retrieval.

func NewManager

func NewManager(embedder Embedder, store Store, opts ...ManagerOption) *Manager

NewManager creates a new memory manager.

func (*Manager) Forget

func (m *Manager) Forget(ctx context.Context, id string) error

Forget deletes a memory by ID.

func (*Manager) Get

func (m *Manager) Get(ctx context.Context, id string) (*Memory, error)

Get retrieves a memory by ID.

func (*Manager) List

func (m *Manager) List(ctx context.Context, opts ListOptions) ([]*Memory, error)

List returns memories matching the given options.

func (*Manager) Recall

func (m *Manager) Recall(ctx context.Context, query string, opts RecallOptions) ([]SearchResult, error)

Recall searches for memories relevant to the query.

func (*Manager) Remember

func (m *Manager) Remember(ctx context.Context, content string, memType MemoryType, metadata map[string]any, opts ...RememberOptions) (*Memory, error)

Remember stores a new memory. The content is embedded automatically.

type ManagerOption

type ManagerOption func(*Manager)

ManagerOption configures the manager.

func WithScorer

func WithScorer(scorer Scorer) ManagerOption

WithScorer sets a custom scorer for retrieval ranking.

type Memory

type Memory struct {
	// ID is the unique identifier.
	ID string

	// Content is the text content of the memory.
	Content string

	// Type classifies this memory.
	Type MemoryType

	// Embedding is the vector representation of the content.
	Embedding []float64

	// Metadata holds arbitrary key-value data.
	Metadata map[string]any

	// Importance is a score from 0 to 1 indicating how important this memory is.
	// Higher values are prioritized in retrieval. Subject to time-based decay.
	Importance float64

	// AccessCount tracks how many times this memory has been retrieved.
	AccessCount int

	// LastAccessedAt is the last time this memory was retrieved.
	LastAccessedAt time.Time

	// CreatedAt is when the memory was created.
	CreatedAt time.Time

	// UpdatedAt is when the memory was last modified.
	UpdatedAt time.Time
}

Memory is a single memory entry with embedding and metadata.

type MemoryType

type MemoryType string

MemoryType classifies the kind of memory stored.

const (
	// TypeConversation stores conversational exchanges.
	TypeConversation MemoryType = "conversation"

	// TypeFact stores factual information (e.g., "user lives in Istanbul").
	TypeFact MemoryType = "fact"

	// TypeProcedure stores procedural knowledge (e.g., "to deploy, run X then Y").
	TypeProcedure MemoryType = "procedure"

	// TypeEpisodic stores event-based memories (e.g., "user reported a bug on March 5").
	TypeEpisodic MemoryType = "episodic"

	// TypeSemantic stores contextual/semantic information.
	TypeSemantic MemoryType = "semantic"
)

type RecallOptions

type RecallOptions struct {
	// Limit is the maximum number of results. Default: 10.
	Limit int

	// Threshold is the minimum similarity score (0-1). Default: 0.5.
	Threshold float64

	// Type filters results to a specific memory type.
	Type MemoryType

	// Metadata filters results by metadata key-value pairs.
	Metadata map[string]any

	// UpdateAccess increments the access count and timestamp of returned memories.
	// Default: true.
	UpdateAccess *bool
}

RecallOptions configures a recall query.

type RememberOptions

type RememberOptions struct {
	// ID sets a custom ID. If empty, a random ID is generated.
	ID string

	// Importance sets the initial importance (0-1). Default: 0.5.
	Importance *float64
}

RememberOptions configures how a memory is stored.

type Scorer

type Scorer interface {
	// Score computes the final score for a search result.
	Score(result SearchResult, now time.Time) float64
}

Scorer computes a final retrieval score combining similarity and importance.

type SearchOptions

type SearchOptions struct {
	// Limit is the maximum number of results. Default: 10.
	Limit int

	// Threshold is the minimum similarity score (0-1). Default: 0.5.
	Threshold float64

	// Type filters results to a specific memory type. Empty = all types.
	Type MemoryType

	// Metadata filters results by metadata key-value pairs.
	Metadata map[string]any
}

SearchOptions configures a similarity search.

type SearchResult

type SearchResult struct {
	// Memory is the matched memory.
	Memory *Memory

	// Similarity is the cosine similarity score (0-1).
	Similarity float64
}

SearchResult is a memory matched by similarity search.

type Store

type Store interface {
	// Put stores or updates a memory. If the memory has an ID that already
	// exists, it is updated. Otherwise, a new memory is created.
	Put(ctx context.Context, memory *Memory) error

	// Get retrieves a memory by ID. Returns nil if not found.
	Get(ctx context.Context, id string) (*Memory, error)

	// Search finds memories similar to the given embedding vector.
	Search(ctx context.Context, embedding []float64, opts SearchOptions) ([]SearchResult, error)

	// List returns memories matching the given options.
	List(ctx context.Context, opts ListOptions) ([]*Memory, error)

	// Delete removes a memory by ID.
	Delete(ctx context.Context, id string) error

	// Close releases any resources held by the store.
	Close() error
}

Store persists and retrieves memories with vector similarity search. Implementations must be safe for concurrent use.