agents-features-memory/ai.koog.agents.local.memory.providers/LocalFileMemoryProvider

LocalFileMemoryProvider

data class LocalFileMemoryProvider<Path>(config: LocalMemoryConfig, storage: Storage<Path>, fs: FileSystemProvider.ReadWrite<Path>, root: Path) : AgentMemoryProvider(source)

File-based implementation of AgentMemoryProvider that provides persistent storage of agent memory using a hierarchical file system structure. This implementation is designed for durability, thread safety, and human readability of stored data.

Key features:

Thread-safe operations using mutex locks
Hierarchical storage structure for efficient organization
JSON-based storage with pretty printing for human readability
Support for multiple memory scopes and subjects
Atomic read/write operations

Storage Structure:

root/
  storageDirectory/
    agent/                    # For MemoryScope.Agent
      [agent-name]/
        subject/
          [subject-name]/
            facts.json
    feature/                  # For MemoryScope.Feature
      [feature-id]/
        subject/
          [subject-name]/
            facts.json
    product/                  # For MemoryScope.Product
      [product-name]/
        subject/
          [subject-name]/
            facts.json
    organization/             # For MemoryScope.CrossProduct
      subject/
        [subject-name]/
          facts.json

Usage example:

val provider = LocalFileMemoryProvider(
    config = LocalMemoryConfig("memory-storage"),
    storage = EncryptedStorage(fileSystem),
    fs = JVMFileSystemProvider,
    root = Path("path/to/root")
)

// Store environment information
provider.save(
    fact = environmentFact,
    subject = MemorySubject.Machine,
    scope = MemoryScope.Agent("env-analyzer")
)

// Retrieve project dependencies
val dependencies = provider.load(
    concept = dependenciesConcept,
    subject = MemorySubject.Project,
    scope = MemoryScope.Product("my-product")
)

Parameters

Path

The type representing file system paths (platform-specific)

Constructors

LocalFileMemoryProvider

constructor(config: LocalMemoryConfig, storage: Storage<Path>, fs: FileSystemProvider.ReadWrite<Path>, root: Path)

Functions

load

open suspend override fun load(concept: Concept, subject: MemorySubject, scope: MemoryScope): List<Fact>

Retrieves facts associated with a specific concept from storage. This method provides efficient concept-based fact retrieval with:

loadAll

open suspend override fun loadAll(subject: MemorySubject, scope: MemoryScope): List<Fact>

Retrieves all facts stored within a specific subject and scope context. This method is useful for:

loadByDescription

open suspend override fun loadByDescription(description: String, subject: MemorySubject, scope: MemoryScope): List<Fact>

Searches for facts using natural language descriptions. This method enables semantic-based fact retrieval by:

save

open suspend override fun save(fact: Fact, subject: MemorySubject, scope: MemoryScope)

Persists a fact to the local storage system with thread-safe guarantees. This method provides atomic updates to the fact collection by: