feat(agentic): Phase 1 — API Foundation

[Copilot]

Introduces the main/api primitives required by all subsequent agentic aggregate phases. Pure Java — no new dependencies.

New Types

• @AgenticAggregateInfo — @Component-composable annotation for singleton agentic aggregates. Exposes stateClass, description, and maxMemories (sliding-window eviction limit, default 100). Deliberately omits generateGDPRKeyOnCreate, indexed/indexName, and partition count (always 1).

• AgenticAggregateMemory — immutable record capturing a single memory entry:

  public record AgenticAggregateMemory(
      String memoryId,   // UUID
      String subject,    // 1–2 word topic
      String fact,       // max 200 chars
      String citations,
      String reason,
      Instant storedAt
  ) {}

• MemoryAwareState — opt-in interface for aggregate state classes that expose memories:

  public interface MemoryAwareState {
      List<AgenticAggregateMemory> getMemories();
  }

• AgenticAggregate<S> — extends Aggregate<S>, adds a default getMemories(S state) that uses pattern matching to delegate to MemoryAwareState or fall back to List.of():

  default List<AgenticAggregateMemory> getMemories(S state) {
      if (state instanceof MemoryAwareState memoryState) {
          return memoryState.getMemories();
      }
      return List.of();
  }

[Copilot]

Pull request overview

Adds initial “agentic aggregate” API primitives to main/api to support later agentic aggregate phases without introducing new dependencies.

Changes:

• Introduces @AgenticAggregateInfo annotation mirroring existing @AggregateInfo Spring composition patterns, with agentic-specific attributes (stateClass, description, maxMemories).
• Adds agentic memory model types: AgenticAggregateMemory and MemoryAwareState.
• Adds AgenticAggregate<S> interface extending Aggregate<S> with a convenience getMemories(S) default method.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

File	Description
main/api/src/main/java/org/elasticsoftware/akces/annotations/AgenticAggregateInfo.java	New Spring-composable annotation for registering agentic aggregates with memory configuration metadata.
main/api/src/main/java/org/elasticsoftware/akces/aggregate/MemoryAwareState.java	New opt-in state interface exposing a list of agentic memories.
main/api/src/main/java/org/elasticsoftware/akces/aggregate/AgenticAggregateMemory.java	New immutable record representing a single “memory” entry (fact + metadata).
main/api/src/main/java/org/elasticsoftware/akces/aggregate/AgenticAggregate.java	New aggregate interface with default getMemories delegation to MemoryAwareState.

[Copilot]

getMemories can return null if a MemoryAwareState implementation returns null from getMemories(), which contradicts the method’s contract of returning a list (or empty list). Consider defensively normalizing to an empty list (and/or returning an unmodifiable copy) to guarantee a non-null result.

Suggested change

	return memoryState.getMemories();
	List<AgenticAggregateMemory> memories = memoryState.getMemories();
	return memories == null ? List.of() : List.copyOf(memories);

[Copilot]

MemoryAwareState#getMemories() doesn’t specify whether it may return null. Since AgenticAggregate#getMemories is documented to return a list (or empty list), it would be safer to define a non-null contract here as well (e.g., annotate the return with @Nonnull and document that implementations must return an empty list instead of null).

Suggested change

	public interface MemoryAwareState {
	import jakarta.annotation.Nonnull;
	public interface MemoryAwareState {
	/**
	* Returns the memories associated with this state.
	* <p>
	* Implementations must never return {@code null}. If no memories are available,
	* an empty list must be returned instead.
	*
	* @return a non-null list of memories, or an empty list if none exist
	*/
	@Nonnull