core
API
Generated with
core/org.llm4s/org.llm4s.agent/org.llm4s.agent.memory

org.llm4s.agent.memory

package org.llm4s.agent.memory

Memory system for agent context and knowledge retention.

The memory package provides a comprehensive system for agents to remember information across conversations, learn about entities, and retrieve relevant context for responses.

== Core Concepts ==

'''Memory Types:'''

  • Conversation - Messages from conversation history
  • Entity - Facts about people, organizations, concepts
  • Knowledge - Information from external documents
  • UserFact - Learned user preferences and background
  • Task - Records of completed tasks and outcomes

'''Components:'''

== Quick Start ==

import org.llm4s.agent.memory._

// Create a memory manager
val manager = SimpleMemoryManager.empty

// Record a user fact
val updated = manager.recordUserFact(
 "User prefers Scala over Java",
 userId = Some("user123")
)

// Record an entity fact
val entityId = EntityId.fromName("Scala")
val withEntity = updated.flatMap(_.recordEntityFact(
 entityId = entityId,
 entityName = "Scala",
 fact = "Scala is a programming language",
 entityType = "technology"
))

// Retrieve relevant context for a query
val context = withEntity.flatMap(_.getRelevantContext("Tell me about Scala"))

== Memory Filtering ==

Filters can be composed for complex queries:

import org.llm4s.agent.memory.MemoryFilter._

// Simple filters
val conversationsOnly = conversations
val importantOnly = important(0.7)

// Combined filters
val recentImportant = after(weekAgo) && important(0.5)
val entityOrKnowledge = entities || knowledge

// Recall with filter
store.recall(recentImportant, limit = 10)

== Storage Backends ==

Multiple backends are available:

  • memory.InMemoryStore - Fast, ephemeral storage for testing
  • (Future) SQLiteStore - Persistent local storage
  • (Future) VectorStore - Semantic search with embeddings

Attributes

See also

memory.SimpleMemoryManager for basic memory management

memory.MemoryFilter for filtering options

Members list

Type members

Classlikes

trait EmbeddingService

Service for generating embeddings for memory content.

Service for generating embeddings for memory content.

This trait abstracts over the embedding generation process, allowing different implementations (LLM providers, local models, etc.).

Attributes

Supertypes
class Object
trait Matchable
class Any
Known subtypes
final case class EntityId(value: String) extends AnyVal

Type-safe wrapper for entity identifiers.

Type-safe wrapper for entity identifiers.

Attributes

Companion
object
Supertypes
trait Serializable
trait Product
trait Equals
class AnyVal
trait Matchable
class Any
Show all
object EntityId

Attributes

Companion
class
Supertypes
class Object
trait Matchable
class Any
Self type
EntityId.type
final case class InMemoryStore extends MemoryStore

In-memory implementation of MemoryStore.

In-memory implementation of MemoryStore.

This implementation stores all memories in memory, making it suitable for testing, short-lived agents, and scenarios where persistence isn't required.

Features:

  • Fast lookups using indexed data structures
  • Basic keyword search (semantic search requires embeddings)
  • Thread-safe for concurrent access
  • No external dependencies

Limitations:

  • Data is lost when the application terminates
  • Memory usage grows with stored memories
  • Keyword search is less sophisticated than vector search

Value parameters

config

Configuration options

memories

All stored memories indexed by ID

Attributes

Companion
object
Supertypes
trait Serializable
trait Product
trait Equals
trait MemoryStore
class Object
trait Matchable
class Any
Show all
object InMemoryStore

Attributes

Companion
class
Supertypes
trait Product
trait Mirror
class Object
trait Matchable
class Any
Self type
final class LLMEmbeddingService extends EmbeddingService

Embedding service using an LLM provider (OpenAI, VoyageAI, etc.).

Embedding service using an LLM provider (OpenAI, VoyageAI, etc.).

Value parameters

client

The embedding client

modelConfig

The model configuration (dimensions, model name)

Attributes

Companion
object
Supertypes
class Object
trait Matchable
class Any
object LLMEmbeddingService

Attributes

Companion
class
Supertypes
class Object
trait Matchable
class Any
Self type
final case class Memory(id: MemoryId, content: String, memoryType: MemoryType, metadata: Map[String, String], timestamp: Instant, importance: Option[Double], embedding: Option[Array[Float]])

A single memory entry in the memory system.

A single memory entry in the memory system.

Memories are immutable records that capture information for later retrieval. They include content, metadata for filtering, and timestamps for recency-based retrieval.

Value parameters

content

The actual content/text of the memory

embedding

Optional pre-computed embedding vector for semantic search

id

Unique identifier for this memory

importance

Optional importance score (0.0 to 1.0) for prioritization

memoryType

Classification of the memory

metadata

Key-value pairs for filtering and context

timestamp

When this memory was created

Attributes

Companion
object
Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
object Memory

Attributes

Companion
class
Supertypes
trait Product
trait Mirror
class Object
trait Matchable
class Any
Self type
Memory.type
sealed trait MemoryFilter

Filter criteria for memory recall.

Filter criteria for memory recall.

MemoryFilters are composable predicates that can be combined to create complex filtering logic for memory retrieval.

Attributes

Companion
object
Supertypes
class Object
trait Matchable
class Any
Known subtypes
object All
class And
class ByEntity
class ByMetadata
class ByTimeRange
class ByType
class ByTypes
class Custom
class HasMetadata
object None
class Not
class Or
Show all
object MemoryFilter

Attributes

Companion
trait
Supertypes
trait Sum
trait Mirror
class Object
trait Matchable
class Any
Self type
final case class MemoryId(value: String) extends AnyVal

Type-safe wrapper for memory identifiers.

Type-safe wrapper for memory identifiers.

Attributes

Companion
object
Supertypes
trait Serializable
trait Product
trait Equals
class AnyVal
trait Matchable
class Any
Show all
object MemoryId

Attributes

Companion
class
Supertypes
class Object
trait Matchable
class Any
Self type
MemoryId.type
trait MemoryManager

High-level memory management for agents.

High-level memory management for agents.

MemoryManager provides semantic operations on top of the raw MemoryStore, including entity extraction, memory consolidation, and intelligent retrieval strategies.

This is the primary interface for agent memory integration.

Attributes

Supertypes
class Object
trait Matchable
class Any
Known subtypes
final case class MemoryManagerConfig(autoRecordMessages: Boolean, autoExtractEntities: Boolean, defaultImportance: Double, contextTokenBudget: Int, consolidationEnabled: Boolean)

Configuration for memory manager behavior.

Configuration for memory manager behavior.

Value parameters

autoExtractEntities

Whether to automatically extract entities from messages

autoRecordMessages

Whether to automatically record conversation messages

consolidationEnabled

Whether to enable automatic memory consolidation

contextTokenBudget

Default token budget for context retrieval

defaultImportance

Default importance score for unscored memories

Attributes

Companion
object
Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
object MemoryManagerConfig

Attributes

Companion
class
Supertypes
trait Product
trait Mirror
class Object
trait Matchable
class Any
Self type
final case class MemoryStats(totalMemories: Long, byType: Map[MemoryType, Long], entityCount: Long, conversationCount: Long, embeddedCount: Long, oldestMemory: Option[Instant], newestMemory: Option[Instant])

Statistics about memory usage.

Statistics about memory usage.

Value parameters

byType

Count of memories by type

conversationCount

Number of distinct conversations

embeddedCount

Number of memories with embeddings

entityCount

Number of distinct entities

newestMemory

Timestamp of newest memory

oldestMemory

Timestamp of oldest memory

totalMemories

Total number of memories stored

Attributes

Companion
object
Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
object MemoryStats

Attributes

Companion
class
Supertypes
trait Product
trait Mirror
class Object
trait Matchable
class Any
Self type
trait MemoryStore

Storage backend for agent memories.

Storage backend for agent memories.

MemoryStore provides the interface for persisting and retrieving memories. Implementations can be in-memory (for testing), file-based, database-backed, or use vector databases for semantic search.

The trait follows functional principles - operations return new instances rather than mutating state.

Attributes

Supertypes
class Object
trait Matchable
class Any
Known subtypes
final case class MemoryStoreConfig(maxMemories: Option[Int], defaultEmbeddingDimensions: Int, enableAutoCleanup: Boolean, cleanupThreshold: Int)

Configuration for memory store behavior.

Configuration for memory store behavior.

Value parameters

cleanupThreshold

Memory count threshold for triggering cleanup

defaultEmbeddingDimensions

Dimensions for embedding vectors

enableAutoCleanup

Whether to automatically clean old memories

maxMemories

Maximum number of memories to retain (None for unlimited)

Attributes

Companion
object
Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
object MemoryStoreConfig

Attributes

Companion
class
Supertypes
trait Product
trait Mirror
class Object
trait Matchable
class Any
Self type
sealed trait MemoryType

Classification of memory types.

Classification of memory types.

Different memory types enable different retrieval strategies and allow for targeted filtering during recall.

Attributes

Companion
object
Supertypes
class Object
trait Matchable
class Any
Known subtypes
object Conversation
class Custom
object Entity
object Knowledge
object Task
object UserFact
Show all
object MemoryType

Attributes

Companion
trait
Supertypes
trait Sum
trait Mirror
class Object
trait Matchable
class Any
Self type
MemoryType.type
final class MockEmbeddingService(val dimensions: Int) extends EmbeddingService

A mock embedding service for testing.

A mock embedding service for testing.

Generates deterministic embeddings based on text content hash. Not suitable for production use.

Attributes

Companion
object
Supertypes
class Object
trait Matchable
class Any
object MockEmbeddingService

Attributes

Companion
class
Supertypes
class Object
trait Matchable
class Any
Self type
final class SQLiteMemoryStore extends MemoryStore

SQLite-backed implementation of MemoryStore.

SQLite-backed implementation of MemoryStore.

Provides persistent storage for memories using SQLite database. Supports full-text search via SQLite FTS5 extension.

Thread Safety: This implementation is NOT thread-safe. For concurrent access, use connection pooling or synchronization.

Value parameters

config

Store configuration

dbPath

Path to SQLite database file (use ":memory:" for in-memory)

Attributes

Companion
object
Supertypes
trait MemoryStore
class Object
trait Matchable
class Any
object SQLiteMemoryStore

Attributes

Companion
class
Supertypes
class Object
trait Matchable
class Any
Self type
final case class ScoredMemory(memory: Memory, score: Double)

A memory with an associated relevance score.

A memory with an associated relevance score.

Used in search results to indicate how well a memory matches the search query.

Value parameters

memory

The memory

score

Relevance score (0.0 to 1.0, higher is more relevant)

Attributes

Companion
object
Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
object ScoredMemory

Attributes

Companion
class
Supertypes
trait Product
trait Mirror
class Object
trait Matchable
class Any
Self type
final case class SimpleMemoryManager extends MemoryManager

Simple implementation of MemoryManager.

Simple implementation of MemoryManager.

This implementation provides basic memory management without requiring an LLM for entity extraction or consolidation. It's suitable for most use cases where you don't need automatic entity recognition.

For advanced features like LLM-powered entity extraction, use LLMMemoryManager instead.

Value parameters

config

Configuration options

store

The underlying memory store

Attributes

Companion
object
Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
object SimpleMemoryManager

Attributes

Companion
class
Supertypes
trait Product
trait Mirror
class Object
trait Matchable
class Any
Self type
final class VectorMemoryStore extends MemoryStore

Memory store with vector embedding support for semantic search.

Memory store with vector embedding support for semantic search.

This store extends SQLite-based storage with embedding vectors, enabling semantic similarity search in addition to keyword search.

Embeddings are generated on-demand using the provided EmbeddingService and stored alongside memories for efficient retrieval.

Value parameters

config

Store configuration

dbPath

Path to SQLite database file

embeddingService

Service for generating embeddings

Attributes

Companion
object
Supertypes
trait MemoryStore
class Object
trait Matchable
class Any
object VectorMemoryStore

Attributes

Companion
class
Supertypes
class Object
trait Matchable
class Any
Self type
object VectorOps

Utilities for working with embedding vectors.

Utilities for working with embedding vectors.

Attributes

Supertypes
class Object
trait Matchable
class Any
Self type
VectorOps.type
final case class VectorStoreStats(totalMemories: Long, embeddedMemories: Long, embeddingDimensions: Set[Int])

Statistics for a vector memory store.

Statistics for a vector memory store.

Attributes

Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all

Types

type ScoredMemories = Seq[ScoredMemory]

Type alias for memory retrieval results with scores.

Type alias for memory retrieval results with scores.

Attributes

Value members

Concrete fields

val memoryByImportanceDesc: Ordering[Memory]

Implicit ordering for memories by importance (highest first).

Implicit ordering for memories by importance (highest first).

Attributes

Implicits

Implicits

implicit val memoryByTimestampDesc: Ordering[Memory]

Implicit ordering for memories by timestamp (most recent first).

Implicit ordering for memories by timestamp (most recent first).

Attributes

Generated with