llm4s-docs
API
Generated with
llm4s-docs/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

@Experimental
final case class AppliedWrite(added: Vector[MemoryId], removed: Vector[MemoryId], evicted: Int)

What one applied write did: the ids it stored, the ids it deleted (only those that were there), and how many memories it evicted to keep the store within its MemoryBounds. Bounded by the write itself, never by the size of the store: evictions are a count.

What one applied write did: the ids it stored, the ids it deleted (only those that were there), and how many memories it evicted to keep the store within its MemoryBounds. Bounded by the write itself, never by the size of the store: evictions are a count.

Attributes

Companion
object
Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
@Experimental
object AppliedWrite

Attributes

Companion
class
Supertypes
trait Product
trait Mirror
class Object
trait Matchable
class Any
Self type
@Experimental
final case class AppliedWriteKey(scope: String, value: String)

The identity of one applied write in a TransactionalMemoryStore: value is the key, scope the fencing scope it belongs to (one per agent thread). llm4s-agent-memory builds it from an agent EffectKey; this module knows no agent type.

The identity of one applied write in a TransactionalMemoryStore: value is the key, scope the fencing scope it belongs to (one per agent thread). llm4s-agent-memory builds it from an agent EffectKey; this module knows no agent type.

Attributes

Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
final case class ConsolidationConfig(maxMemoriesPerGroup: Int, strictMode: Boolean)

Configuration for memory consolidation behavior.

Configuration for memory consolidation behavior.

Read by consolidateMemories whenever it is called. Nothing consolidates on its own: call consolidateMemories when your application decides to.

Value parameters

maxMemoriesPerGroup

Maximum memories per consolidation group (prevents unbounded context)

strictMode

If true, fail fast on any consolidation error. If false, log and continue (best-effort)

Attributes

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

Attributes

Companion
class
Supertypes
trait Product
trait Mirror
class Object
trait Matchable
class Any
Self type
object ConsolidationPrompts

LLM prompts for memory consolidation.

LLM prompts for memory consolidation.

This object provides prompt templates for consolidating different types of memories using LLM summarization.

Attributes

Supertypes
class Object
trait Matchable
class Any
Self type
final class EmbeddingMemoryStore extends MemoryStore

A memory store wrapper that adds embedding-based semantic search to an underlying store.

A memory store wrapper that adds embedding-based semantic search to an underlying store.

This wrapper implements the decorator pattern - it delegates all standard operations to the inner store while overriding search() to use vector similarity when embeddings are available.

Binary Compatibility Note: This class was extracted from InMemoryStore to preserve the original case class signature and maintain binary compatibility with v0.1.4.

Value parameters

embeddingService

The embedding service for generating query embeddings

inner

The underlying memory store

Attributes

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

Attributes

Companion
class
Supertypes
class Object
trait Matchable
class Any
Self type
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 TransactionalMemoryStore

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
  • Whole-word keyword search, case-insensitive (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 LLMMemoryManager(config: MemoryManagerConfig, store: MemoryStore, client: LLMClient)

Memory manager with LLM-powered consolidation and entity extraction.

Memory manager with LLM-powered consolidation and entity extraction.

Extends basic memory management with advanced features:

  • Automatic memory consolidation using LLM summarization
  • Entity extraction from conversation text
  • Importance scoring for extracted entities

This implementation follows the same patterns as SimpleMemoryManager but adds LLM-powered intelligence for memory operations.

Value parameters

client

LLM client for consolidation and extraction

config

Configuration for memory management

store

Underlying memory store

Attributes

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

Attributes

Companion
class
Supertypes
trait Product
trait Mirror
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. 1.0 represents critical facts, while 0 represents trivial details. If None, system treats it as neutral importance.

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
@Experimental
final case class MemoryBounds

How much one store may hold: at most maxMemories memories and maxBytes bytes, measured by MemoryBounds.sizeOf. A TransactionalMemoryStore enforces both in the transaction that adds, by evicting.

How much one store may hold: at most maxMemories memories and maxBytes bytes, measured by MemoryBounds.sizeOf. A TransactionalMemoryStore enforces both in the transaction that adds, by evicting.

Attributes

Companion
object
Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
@Experimental
object MemoryBounds

Attributes

Companion
class
Supertypes
trait Product
trait Mirror
class Object
trait Matchable
class Any
Self 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

Companion
object
Supertypes
class Object
trait Matchable
class Any
object MemoryManager

Attributes

Companion
trait
Supertypes
class Object
trait Matchable
class Any
Self type
final case class MemoryManagerConfig

Configuration for memory manager behavior.

Configuration for memory manager behavior.

A plain value built in code; this module reads no configuration file. Build one with MemoryManagerConfig(...) (every option has a default) or a preset, and change it with the with* setters; there is no public constructor or copy, so the type can gain options without breaking callers. Every option is read by the managers that extend the shared record/retrieve operations (SimpleMemoryManager and LLMMemoryManager).

Value parameters

autoExtractEntities

When true, recordMessage (and so recordConversation) also runs extractEntities over the content of each user and assistant message it records, passing the conversation id. System and tool messages are not analysed. Extraction is best-effort: if it fails, the message stays recorded and the failure is logged as a warning. A cancellation is not a failure: it is returned, so the caller stops. SimpleMemoryManager extracts nothing, so the option only changes what LLMMemoryManager stores (one extra LLM call per message).

consolidationConfig

How consolidateMemories groups memories and handles errors

contextTokenBudget

Token budget getRelevantContext uses when the call passes no maxTokens. An explicit maxTokens always wins.

defaultImportance

Importance score given to memories recorded without one

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
Show all
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 PostgresMemoryStore extends TransactionalMemoryStore, AutoCloseable

PostgreSQL implementation of MemoryStore. Persists agent memories to a Postgres table using JDBC.

PostgreSQL implementation of MemoryStore. Persists agent memories to a Postgres table using JDBC.

Built either by PostgresMemoryStore.apply, which creates a connection pool and closes it on close, or by PostgresMemoryStore.fromDataSource, over a javax.sql.DataSource the caller owns and keeps open.

Attributes

Companion
object
Supertypes
trait AutoCloseable
trait MemoryStore
class Object
trait Matchable
class Any
Show all
object PostgresMemoryStore

Attributes

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

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.

Writes: store and storeAll are each one transaction - a batch is stored whole or not at all - and so are deleteMatching and opening the store. A write takes the database's write lock when it begins, waiting up to the connection's busy timeout (sqlite-jdbc's default, 3 seconds) for a writer on another connection to the same file.

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

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
@Experimental
trait TransactionalMemoryStore extends MemoryStore

A MemoryStore that applies a write and records it under a key in one transaction, so that a write run again after a crash is not applied twice (the Transactional replay class of the agent runtime, design §4.24 and §4.31).

A MemoryStore that applies a write and records it under a key in one transaction, so that a write run again after a crash is not applied twice (the Transactional replay class of the agent runtime, design §4.24 and §4.31).

Every method is one transaction, fenced by token: the store keeps, for each key scope, the newest token any operation on that scope has carried. An operation with an older token is refused with a Left and changes nothing; otherwise its token becomes the scope's newest and it goes ahead. So a writer that has lost its claim can neither apply, nor read back, nor forget anything once its successor has touched the store.

Applied keys are removed only by forgetApplied; clear() keeps them, and the fencing tokens.

Each method returns the store to use next: InMemoryStore is immutable, so its applied keys and tokens are part of its value. The SQL stores return themselves.

Attributes

Supertypes
trait MemoryStore
class Object
trait Matchable
class Any
Known subtypes
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.

Writes: store and storeAll are each one transaction - a batch is stored whole or not at all - and so are deleteMatching and opening the store. A write takes the database's write lock when it begins, waiting up to 30 seconds (the connection's busy timeout) for a writer in another instance or process on the same file.

Thread safety: one instance holds one JDBC connection and is not safe for concurrent use; share it between threads only under your own synchronization. Separate instances, in one process or several, may write the same file concurrently: SQLite serialises their transactions.

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