feat(agentic): Phase 1 — API Foundation

[jwijgerd]

Phase 1: API Foundation

Tracking issue: #284
Module: main/api
Can start: Immediately
Blocks: Phase 2, Phase 3, Phase 4, Phase 5

📋 Plan reference: plans/agentic-aggregates.md → Phase 1: API Foundation

---

Overview

Introduce the new API types in main/api that form the foundation of the AgenticAggregate concept. These types are framework-level primitives referenced by all subsequent phases.

No new dependencies are introduced — this is pure Java interfaces, annotations, and records.

---

Tasks

1. @AgenticAggregateInfo Annotation

Create org.elasticsoftware.akces.annotations.AgenticAggregateInfo:

• Annotated with @Retention(RetentionPolicy.RUNTIME), @Target({ElementType.TYPE}), @Component
• Attributes:
  • String value() — Spring component bean name (aliased via @AliasFor(annotation = Component.class))
  • Class<? extends AggregateState> stateClass() — the aggregate's state class
  • String description() default "" — optional human-readable description
  • int maxMemories() default 100 — sliding window capacity for the memory system
• Intentionally omitted (vs @AggregateInfo):
  • No generateGDPRKeyOnCreate — no PIIData support in memories
  • No indexed / indexName — singletons are not indexed
  • No partition count — always 1 partition (enforced by runtime)

2. AgenticAggregate Interface

Create org.elasticsoftware.akces.aggregate.AgenticAggregate<S extends AggregateState>:

• Extends Aggregate<S>
• Adds a default method:

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

• This provides type-safe, optional access to memories without requiring all states to implement MemoryAwareState

3. MemoryAwareState Interface

Create org.elasticsoftware.akces.aggregate.MemoryAwareState:

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

• Implemented by user-defined aggregate state classes to enable the memory system
• Decoupled from AgenticAggregate itself so the state model stays clean

4. AgenticAggregateMemory Record

Create org.elasticsoftware.akces.aggregate.AgenticAggregateMemory:

public record AgenticAggregateMemory(
    String memoryId,   // UUID
    String subject,    // 1–2 word topic, e.g. "naming conventions"
    String fact,       // The fact to remember (max 200 chars)
    String citations,  // Source of the fact
    String reason,     // Why this fact is being stored
    Instant storedAt
) {}

---

Acceptance Criteria

• @AgenticAggregateInfo annotation is in main/api and compiles cleanly
• AgenticAggregate interface extends Aggregate and provides getMemories() default method
• MemoryAwareState interface is in main/api and has a single getMemories() method
• AgenticAggregateMemory record is in main/api with all 6 fields
• No new dependencies added to main/api/pom.xml
• All existing main/api tests still pass (mvn test in main/api)
• Code follows Java 25 conventions (records, sealed types where appropriate)