Package dev.agenor.core.memory

Interface MemoryStore

All Known Implementing Classes:
InMemoryStore
public interface MemoryStore
Core interface for agent memory storage.

Provides persistent and volatile storage for agent memories with support for:

  • Short-term (volatile) and long-term (persistent) memory scopes
  • Full-text search and metadata filtering
  • Shared memory across multiple agents
  • Automatic expiration of time-limited memories

All operations are asynchronous and return CompletableFuture for non-blocking execution.

Thread Safety: All implementations must be thread-safe.

Implementation Notes:

  • SHORT_TERM memories may be stored in-memory for fast access
  • LONG_TERM memories should be persisted to durable storage
  • Expired entries should be automatically removed during queries
  • Search operations should support both exact and fuzzy matching

Example usage: 


 MemoryStore store = new InMemoryStore();

 // Store a memory
 MemoryEntry entry = MemoryEntry.builder("User prefers email notifications")
     .ownerId("notification-agent")
     .metadata("preference", "email")
     .build();

 store.store("pref:user123:notification", entry, MemoryScope.LONG_TERM)
     .thenRun(() -> System.out.println("Memory stored"));

 // Retrieve a memory
 store.retrieve("pref:user123:notification", MemoryScope.LONG_TERM)
     .thenAccept(opt -> opt.ifPresent(e ->
         System.out.println("Found: " + e.content())));

 // Search memories
 MemoryQuery query = MemoryQuery.builder()
     .text("notification")
     .scope(MemoryScope.LONG_TERM)
     .ownerId("notification-agent")
     .limit(10)
     .build();

 store.search(query)
     .thenAccept(results ->
         System.out.println("Found " + results.size() + " memories"));
Since:
0.6.0
See Also:

  • Method Details

    • store

      CompletableFuture<Void> store(String key, MemoryEntry entry, MemoryScope scope)
      Stores a memory entry.

      If an entry with the same key and scope already exists, it will be replaced.

      Parameters:
      key - unique identifier for this memory
      entry - the memory entry to store
      scope - the memory scope (SHORT_TERM or LONG_TERM)
      Returns:
      a future that completes when the entry is stored
      Throws:
      MemoryException - if the storage operation fails
      IllegalArgumentException - if key is null or blank

    • retrieve

      CompletableFuture<Optional<MemoryEntry>> retrieve(String key, MemoryScope scope)
      Retrieves a memory entry by key.

      Expired entries are automatically filtered out and return empty.

      Parameters:
      key - the memory key
      scope - the memory scope to search in
      Returns:
      a future containing the memory entry, or empty if not found
      Throws:
      MemoryException - if the retrieval operation fails
      IllegalArgumentException - if key is null or blank

    • search

      CompletableFuture<List<MemoryEntry>> search(MemoryQuery query)
      Searches for memory entries matching the query criteria.

      Results are filtered by:

      • Text content (if specified)
      • Owner ID (if specified)
      • Metadata filters (if specified)
      • Non-expired entries only

      Results may be returned in any order unless the implementation specifies otherwise.

      Parameters:
      query - the search query parameters
      Returns:
      a future containing matching memory entries (may be empty)
      Throws:
      MemoryException - if the search operation fails
      IllegalArgumentException - if query is null

    • delete

      CompletableFuture<Void> delete(String key, MemoryScope scope)
      Deletes a memory entry.

      If the entry does not exist, this operation completes successfully without error (idempotent).

      Parameters:
      key - the memory key to delete
      scope - the memory scope
      Returns:
      a future that completes when the entry is deleted
      Throws:
      MemoryException - if the deletion operation fails
      IllegalArgumentException - if key is null or blank

    • clear

      CompletableFuture<Void> clear(MemoryScope scope)
      Clears all memory entries in the specified scope.

      Warning: This operation cannot be undone. Use with caution.

      Parameters:
      scope - the memory scope to clear
      Returns:
      a future that completes when all entries are cleared
      Throws:
      MemoryException - if the clear operation fails

    • listKeys

      CompletableFuture<List<String>> listKeys(MemoryScope scope)
      Lists all memory keys in the specified scope.

      This operation may be expensive for large memory stores. Consider using search(MemoryQuery) with pagination instead.

      Parameters:
      scope - the memory scope
      Returns:
      a future containing all keys (may be empty)
      Throws:
      MemoryException - if the list operation fails

    • getStats

      default MemoryStats getStats()
      Gets statistics about memory usage.

      Statistics may be cached and not reflect the absolute current state.

      Returns:
      memory usage statistics

    • exists

      default CompletableFuture<Boolean> exists(String key, MemoryScope scope)
      Checks if a memory entry exists.

      This is more efficient than retrieve(String, MemoryScope) when only existence needs to be checked.

      Parameters:
      key - the memory key
      scope - the memory scope
      Returns:
      a future containing true if the entry exists and is not expired
      Throws:
      MemoryException - if the check operation fails

    • getStoreName

      default String getStoreName()
      Gets the name of this memory store implementation.

      Used for logging and monitoring.

      Returns:
      the store name (e.g., "InMemoryStore", "DatabaseStore")