feat(embabel): Phase 2 — Akces Embabel Component (Goals, Actions, Conditions)

[jwijgerd]

Phase 2: Akces Embabel Component — Goals, Actions, and Conditions

Replaces: #306 (please close that issue)
Incorporates changes from: PR #303

Tracking issue: #311
Module: main/agentic
Can start: After Phase 1 + Annotation Extensions (#312) is merged
Can run concurrently with: Phase 3
Blocks: Phase 4

📋 Plan reference: Phase 2: Create Akces Embabel Component with Goals, Actions, and Conditions (lines 339–450)

---

Overview

Create a new @EmbabelComponent class (AkcesAgentComponent) that houses reusable Goals, Actions, and Conditions for Akces-based agentic systems. These are the foundational agent capabilities — memory management and knowledge learning — that Embabel automatically discovers and makes available to agents.

Package: org.elasticsoftware.akces.agentic.agent

---

Tasks

2.1 Create AkcesAgentComponent — The @EmbabelComponent Class

• New class annotated with @EmbabelComponent (which includes @Component)
• Houses reusable Goals, Actions, and Conditions
• Automatically discovered by AgentPlatform via component scanning

2.2 Memory Management Action: StoreMemoryAction

• @Action(description = "Store a learned fact as a memory entry for the agentic aggregate")
• Reads aggregate ID from blackboard
• Takes subject, fact, citations, reason as inputs
• Produces a MemoryStoredEvent directly (bypasses internal command path)
• Event is applied through built-in @EventSourcingHandler (calls MemoryAwareState.withMemory())

2.3 Memory Management Action: ForgetMemoryAction

• @Action(description = "Revoke a memory entry that is no longer relevant or accurate")
• Takes memoryId and reason from blackboard
• Produces a MemoryRevokedEvent
• Event applied through built-in @EventSourcingHandler (calls MemoryAwareState.withoutMemory())
• Enables agent self-management of its knowledge base

2.4 Memory Retrieval Action: RecallMemoriesAction

• @Action(description = "Search stored memories by subject or keyword to retrieve relevant facts", readOnly = true)
• Reads List<AgenticAggregateMemory> from blackboard
• Filters by subject match, keyword in fact/reason, or returns all
• Returns matching memories as structured result
• Declared readOnly = true (no side effects)

2.5 Condition: HasMemoriesCondition

• @Condition(name = "hasMemories")
• Returns true if blackboard contains one or more AgenticAggregateMemory objects
• Used as precondition for actions that depend on prior knowledge

2.6 Condition: HasAggregateStateCondition — REMOVED

This condition has been removed. Agentic aggregates are singletons — the framework ensures state is always created automatically.

2.7 Goal: LearnFromProcessGoal

• Goal: "LearnFromProcess" — "Analyze current session information and distill useful memories"
• Why a Goal and not an Action: Memory distillation requires multi-step LLM reasoning over Blackboard session context (original command/event, state, produced events, existing memories, aggregate service records), then dispatches to StoreMemoryAction/ForgetMemoryAction as execution primitives. This separation of analysis (LLM reasoning within the Goal) from execution (Actions) is a fundamental Embabel pattern.
• Constraints:
  • Maximum 3 new memories per agent process execution (prevents memory bloat)
  • No duplicate memories — check existing memories before storing
  • Memory capacity enforcement — after storing, if total exceeds maxMemories, evict oldest via ForgetMemoryAction. This replaces the previous enforceMemorySlidingWindow() mechanism — the agent itself is now responsible for capacity management.
  • Memory field guidance (subject: 1–3 word topic, fact: max ~200 chars, citations: source reference, reason: 2–3 sentences)
• Plan:
  1. RecallMemoriesAction → check existing memories (avoid duplicates, assess capacity)
  2. (LLM reasoning over Blackboard session context) → determine new facts, respect max-3 limit
  3. StoreMemoryAction → persist new memories (MemoryStoredEvent)
  4. ForgetMemoryAction → evict oldest if capacity exceeded, or replace outdated (MemoryRevokedEvent)

---

Changes from PR #303

• LearnFromProcessGoal description updated: now explicitly responsible for memory capacity enforcement (replaces enforceMemorySlidingWindow())
• Clarified Goal vs Action distinction: multi-step LLM reasoning requires a Goal, not a single Action
• Memory commands deletion: StoreMemoryCommand/ForgetMemoryCommand are scheduled for deletion as memory management moves entirely to Embabel Actions

---

Acceptance Criteria

• AkcesAgentComponent is annotated with @EmbabelComponent and is discoverable by AgentPlatform
• StoreMemoryAction produces valid MemoryStoredEvent from blackboard context
• ForgetMemoryAction produces valid MemoryRevokedEvent from blackboard context
• RecallMemoriesAction correctly filters memories by subject/keyword and is readOnly
• HasMemoriesCondition correctly evaluates memory presence on blackboard
• LearnFromProcessGoal enforces max-3 memories, no-duplicate, and memory capacity constraints
• All actions produce events directly (not commands)
• All existing tests still pass
• Code follows Java 25 conventions with JavaDoc