diff --git a/MEMORY_DRIVEN_ARCHITECTURE.md b/MEMORY_DRIVEN_ARCHITECTURE.md new file mode 100644 index 0000000..5204c96 --- /dev/null +++ b/MEMORY_DRIVEN_ARCHITECTURE.md @@ -0,0 +1,683 @@ +# Memory-Driven Architecture for Poimen Workflows + +## Executive Summary + +Poimen state machine (10 phases, 80 tasks, 10 composition gates) will consume Memory Service context & skills to: +- **Learn** from execution attempts (L1 knowledge) +- **Diagnose** failures using memory (three-tier retrieval) +- **Document** decisions for future runs (L2 knowledge) +- **Optimize** prompts with relevant context before agent execution +- **Track** tools, skills, and pattern usage across the harness lifecycle + +This document outlines how Temporal activities integrate with the existing state machine to create a memory-driven, self-improving workflow system. + +--- + +## Current State Machine Architecture + +``` +Poimen Harness (Rust + JSON-RPC) + ├─ Kernel (Event Log + State Machine) + ├─ 10 Phases (T0-T10) + ├─ 80 Tasks (70 build + 10 composition gates) + ├─ WorkflowDef IR (YAML + Rust builder) + └─ 3 Ports (Verifier, Judge, ModelProvider) +``` + +### Key Components + +**WorkflowDef (IR)**: Canonical hash of workflow definition +- YAML declares: steps, transitions, retry policy, budgets +- Rust implements: verifier logic, judge logic, model behavior + +**State Machine**: Event-sourced, immutable audit trail +- Events: WorkerEvent enum +- Attempts: AttemptState with context partition capture +- Folds: re-derive state from event log + +**Run Executor**: Poll-based with: +- Retry policy per step +- Budget tracking (attempts, tokens, time) +- Context partition per attempt + +--- + +## Memory Service Integration Points + +### Architecture Diagram + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ Poimen Workflow │ +│ │ +│ ┌──────────────────────────────────────────────────────────┐ │ +│ │ T1-T10: Task Execution Loop │ │ +│ │ │ │ +│ │ ┌─────────────────────────────────────────────────────┐ │ │ +│ │ │ For each step in workflow: │ │ │ +│ │ │ │ │ │ +│ │ │ 1. RetrieveContext (Memory Service) │ │ │ +│ │ │ ├─ Tool: executor type (planner/judge/impl) │ │ │ +│ │ │ ├─ Task: step name │ │ │ +│ │ │ └─ Returns: tier-1 (signature) + tier-2 (ML) │ │ │ +│ │ │ │ │ │ +│ │ │ 2. OptimizePrompt (with context) │ │ │ +│ │ │ ├─ Add learned facts from memory │ │ │ +│ │ │ ├─ Include skill usage examples │ │ │ +│ │ │ └─ Attach budget constraints │ │ │ +│ │ │ │ │ │ +│ │ │ 3. ExecuteStep (ModelProvider) │ │ │ +│ │ │ └─ Agent uses optimized prompt │ │ │ +│ │ │ │ │ │ +│ │ │ 4. OnStepComplete: │ │ │ +│ │ │ ├─ Success? → LearnFromExecution │ │ │ +│ │ │ ├─ Failure? → AnalyzeError │ │ │ +│ │ │ └─ DocumentDecision (all paths) │ │ │ +│ │ │ │ │ │ +│ │ └─────────────────────────────────────────────────────┘ │ │ +│ └──────────────────────────────────────────────────────────┘ │ +│ ↕ │ +│ ┌──────────────────────────────────────────────────────────┐ │ +│ │ Memory Service (PostgreSQL + OpenSearch + Vault) │ │ +│ │ │ │ +│ │ ├─ L1 Knowledge: Task execution results │ │ +│ │ ├─ L2 Knowledge: Verified patterns & decisions │ │ +│ │ ├─ R (Reference): Docs, skill examples, guides │ │ +│ │ └─ Vault: Organized facts by tool/phase/domain │ │ +│ └──────────────────────────────────────────────────────────┘ │ +│ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +### Memory Service Activities Flow + +``` +Workflow Step Execution → Memory Activities → Response + +1. PRE-EXECUTION (Before step runs) + ┌─────────────────────────────────┐ + │ ExecuteGetContext Activity │ + │ ├─ Input: tool, task, budget │ + │ ├─ Retrieval: 3-tier │ + │ │ ├─ Tier 1: Signature match │ + │ │ │ (exact failure patterns) │ + │ │ ├─ Tier 2: Vector search │ + │ │ │ (learned from similar) │ + │ │ └─ Tier 3: References │ + │ │ (docs, skill guides) │ + │ └─ Returns: Lessons + Skills │ + └─────────────────────────────────┘ + ↓ + ┌─────────────────────────────────┐ + │ Prompt Optimization │ + │ ├─ Add context lessons │ + │ ├─ Inject skill examples │ + │ └─ Set budget constraints │ + └─────────────────────────────────┘ + +2. EXECUTION + ┌─────────────────────────────────┐ + │ Agent executes with context │ + │ (planner/judge/implementer) │ + └─────────────────────────────────┘ + +3. POST-EXECUTION (After step completes) + ┌─────────────────────────────────┐ + │ if SUCCESS: │ + │ ExecuteLearnFromExecution │ + │ ├─ taskID: step name │ + │ ├─ result: output │ + │ ├─ tags: [tool, phase] │ + │ └─ Returns: knowledgeID │ + ├──────────────────────────────────┤ + │ if FAILURE: │ + │ ExecuteAnalyzeError │ + │ ├─ errorMsg: failure message │ + │ ├─ Returns: recovery steps │ + │ └─ (helps with retry) │ + ├──────────────────────────────────┤ + │ ALWAYS: │ + │ ExecuteDocumentDecision │ + │ ├─ Type: phase milestone │ + │ ├─ Decision: action taken │ + │ └─ Reasoning: why chosen │ + └─────────────────────────────────┘ +``` + +--- + +## Skills and Context in State Machine + +### Skill Types + +**Tool Skills** (Skill Category 1): +``` +┌──────────────────────────────────────┐ +│ Tool Skills (Executor capabilities) │ +├──────────────────────────────────────┤ +│ • planner-best-practices │ (T1.3: Plan generation) +│ • judge-evaluation-patterns │ (T1.5: Rubric application) +│ • implementer-code-patterns │ (T2.1: Code generation) +│ • verifier-logic-chains │ (T1.4: Verification) +└──────────────────────────────────────┘ +``` + +**Domain Skills** (Skill Category 2): +``` +┌──────────────────────────────────────┐ +│ Domain Skills (Phase-specific) │ +├──────────────────────────────────────┤ +│ • T0: State machine kernel │ Event log, fork, rewind +│ • T1: Workflow execution │ Attempt lifecycle, budgets +│ • T2: Error recovery │ Crash matrix, checkpoints +│ • T3: IR canonicalization │ YAML ↔ Rust equivalence +│ • T4-T10: Specialization │ Phase-specific patterns +└──────────────────────────────────────┘ +``` + +**Pattern Skills** (Skill Category 3): +``` +┌──────────────────────────────────────┐ +│ Pattern Skills (Cross-cutting) │ +├──────────────────────────────────────┤ +│ • retry-strategy │ Exponential backoff +│ • budget-tracking │ Token/attempt/time limits +│ • composition-gates │ Phase completion criteria +│ • schema-evolution │ Backward compatibility +└──────────────────────────────────────┘ +``` + +### Context Hierarchy + +``` +WorkflowContext (L0 - Always available) +├─ WorkflowDef (IR + hash) +├─ PhaseId (T0-T10) +├─ StepId (current step) +└─ AttemptState (attempt #, budget) + ├─ Attempt context (attempt-scoped) + ├─ Decision points (retry/abort) + └─ Cost ledger (tokens spent) + +TaskContext (L1 - Learned from execution) +├─ Tool type (planner/judge/impl) +├─ Execution results (input/output) +├─ Failure patterns (error signatures) +└─ Retry outcomes (success rates) + +ReferenceContext (L2 - From vault) +├─ Skill documentation +├─ Best practices (YAML-level) +├─ Code patterns (Rust-level) +└─ Design rationale +``` + +--- + +## Activity Usage Per Phase + +### Phase 0-2 (Kernel & Execution Foundation) + +``` +T0: State Machine Kernel +├─ GetContextActivity +│ └─ Retrieve lessons on event log patterns +├─ LearnFromExecutionActivity +│ └─ Record fold/rewind operations +└─ DocumentDecisionActivity + └─ Track checkpointing decisions + +T1: Attempt Lifecycle +├─ GetContextActivity +│ ├─ Tier 1: Known retry patterns +│ └─ Tier 2: Attempt budget tracking +├─ DiagnoseIssueActivity (on failure) +│ ├─ Search for "budget exhausted" patterns +│ └─ Find recovery step limits +└─ LearnFromExecutionActivity + └─ Record successful attempt patterns + +T2: Error Recovery +├─ GetContextActivity +│ └─ Crash matrix lessons +├─ AnalyzeErrorActivity +│ ├─ Match against crash patterns +│ └─ Return recovery procedure +└─ DocumentDecisionActivity + └─ Log recovery action chosen +``` + +### Phase 3-5 (IR & Canonicalization) + +``` +T3: WorkflowDef IR +├─ GetContextActivity +│ └─ Tier 1: Canonical hash failures +├─ SearchKnowledgeActivity +│ └─ "YAML builder equivalence" patterns +└─ DocumentDecisionActivity + └─ IR versioning decisions + +T4: Schema Evolution +├─ GetContextActivity +│ └─ Backward compatibility lessons +├─ DiagnoseIssueActivity +│ └─ Upcaster failure diagnosis +└─ LearnFromExecutionActivity + └─ Schema migration successes + +T5: Storage Abstraction +├─ SearchKnowledgeActivity +│ └─ DB migration patterns +└─ DocumentDecisionActivity + └─ Storage backend selection +``` + +### Phase 6-8 (Orchestration & APIs) + +``` +T6: Orchestrator +├─ GetContextActivity +│ ├─ Tool: orchestrator +│ ├─ Task: workflow step dispatch +│ └─ Returns: step ordering lessons +├─ SearchKnowledgeActivity +│ └─ Query ordering patterns +└─ LearnFromExecutionActivity + └─ Successful step sequences + +T7: HTTP API +├─ DiagnoseIssueActivity (on API error) +│ └─ Match error codes to recovery +└─ DocumentDecisionActivity + └─ Rate limit/timeout decisions + +T8: Observability +├─ SearchKnowledgeActivity +│ └─ Logging pattern queries +└─ RefreshMemoryActivity + └─ Periodic metric snapshots +``` + +### Phase 9-10 (Delivery & Completion) + +``` +T9: Deployment +├─ GetContextActivity +│ ├─ Tool: deployment executor +│ └─ Task: artifact rollout +├─ DiagnoseIssueActivity (on deployment failure) +│ └─ Canary issues, rollback strategies +└─ AnalyzeErrorActivity + └─ Find deployment-specific solutions + +T10: CLI & Metrics +├─ SearchKnowledgeActivity +│ └─ Transcript formatting patterns +├─ LearnFromExecutionActivity +│ └─ User interaction patterns +└─ DocumentDecisionActivity + └─ Metric collection decisions +``` + +--- + +## Prompt Optimization with Memory Context + +### Before (Current) + +```go +prompt := fmt.Sprintf(` +Execute step: %s +Workflow: %s +Budget: %d tokens + +Task: %s +`) +``` + +### After (Memory-Optimized) + +```go +// 1. Get context from memory +ctx, err := ExecuteGetContext( + wfCtx, + "planner", // tool type + "T1.3-run-executor", // task name + 4096, // budget +) +if err != nil { + log.Warn("memory unavailable, continue without context") + ctx = nil +} + +// 2. Build prompt with lessons +lessons := "" +if ctx != nil && len(ctx.Lessons) > 0 { + // Add tier-1 (signature matches) + for _, lesson := range ctx.Lessons { + if lesson.Tier == 1 { + lessons += fmt.Sprintf("Known pattern: %s\n", lesson.Text) + } + } +} + +// 3. Inject skills +skills := "" +if ctx != nil && len(ctx.Skills) > 0 { + for _, skill := range ctx.Skills { + skills += fmt.Sprintf("Skill %s: %s\n", skill.Name, skill.Why) + } +} + +// 4. Build optimized prompt +prompt := fmt.Sprintf(` +Execute step: %s +Workflow: %s +Budget: %d tokens + +# Learned Patterns +%s + +# Skills to Apply +%s + +# Instructions +%s +`, stepName, workflowId, budget, lessons, skills, instructions) + +// 5. Send to agent with enriched context +response := agent.Execute(prompt) + +// 6. Learn from result +ExecuteLearnFromExecution( + wfCtx, + stepName, + response.Text, + []string{"phase", "tool", "status"}, +) +``` + +--- + +## Tool Usage Summary + +### Basic Tools + +**Core Workflow Tools**: +- `State Machine Events`: Insert events, compute state +- `WorkflowDef Builder`: Create IR programmatically +- `Run Executor`: Poll and execute steps +- `Attempt Lifecycle`: Retry, checkpoint, rewind + +**Testing Tools**: +- `Harness`: Verification framework +- `Integration Tests`: Phase composition gates +- `Verify Script`: Assertion + diff runner + +### Memory-Integrated Tools + +**New with Memory Service**: +- `ExecuteGetContext`: Retrieve 3-tier context +- `ExecuteLearnFromExecution`: Capture task results +- `ExecuteAnalyzeError`: Diagnosis on failure +- `ExecuteDocumentDecision`: Log milestones +- `ExecuteSearchKnowledge`: Find patterns +- `ExecuteHealthCheck`: Verify service readiness + +**Memory Vault Organization**: +``` +vault/ +├─ tools/ +│ ├─ planner/ +│ │ └─ best-practices.md +│ ├─ judge/ +│ │ └─ rubric-patterns.md +│ └─ verifier/ +│ └─ logic-chains.md +├─ phases/ +│ ├─ T0-kernel/ +│ ├─ T1-execution/ +│ └─ T2-recovery/ +├─ patterns/ +│ ├─ retry-strategies.md +│ ├─ budget-tracking.md +│ └─ error-signatures.md +└─ skills/ + ├─ schema-evolution.md + ├─ composition-gates.md + └─ ir-canonicalization.md +``` + +--- + +## State Machine Consumption Model + +### Step Execution with Memory + +```rust +// In RunExecutor::execute_step() + +fn execute_step( + &self, + workflow: &WorkflowDef, + step: &StepId, + attempt: &AttemptState, +) -> Result { + // 1. Pre-execution: Retrieve context + let context = self.memory_svc + .retrieve_context( + "tool_type", // planner/judge/implementer + format!("{:?}", step), // step name + attempt.budget.remaining_tokens, + ) + .await + .ok(); // Fail gracefully if memory unavailable + + // 2. Optimize prompt with memory lessons + let prompt = self.optimize_prompt( + &workflow.def, + step, + context.as_ref(), // Lessons + skills + ); + + // 3. Execute step with agent + let output = self.model_provider.run( + &self.model_id, + &prompt, + &attempt.budget, + ).await?; + + // 4. Post-execution: Learn or diagnose + if output.status == StepStatus::Success { + self.memory_svc + .learn_from_execution( + format!("{:?}", step), + output.text.clone(), + vec!["tool", "phase"], + ) + .await + .ok(); // Non-blocking + } else { + self.memory_svc + .analyze_error( + &output.error_message, + ) + .await + .ok(); // Returns recovery suggestions + } + + // 5. Document decision + self.memory_svc + .document_decision( + "step_completion", + output.text.clone(), + format!("Attempt {}", attempt.number), + ) + .await + .ok(); + + Ok(output) +} +``` + +### Retry Policy Integration + +```rust +// In AttemptState::should_retry() + +fn should_retry(&self, error: &Error) -> bool { + // 1. Check budget first + if self.budget.attempts_remaining == 0 { + return false; + } + + // 2. Consult memory for pattern + let recovery = self.memory_svc + .analyze_error(&error.message) + .await + .ok(); + + // 3. If memory suggests retry strategy, use it + if let Some(recovery_steps) = recovery { + for step in recovery_steps { + if step.level == "L1" { // High confidence + return step.suggests_retry(); + } + } + } + + // 4. Fall back to default policy + self.retry_policy.should_retry(self.number, error) +} +``` + +--- + +## Flow Diagram: Memory-Driven Lifecycle + +``` + Workflow Initiated + │ + ↓ + ┌───────────────┐ + │ Phase T0-T10 │ + └───────┬───────┘ + │ + ┌─────────────┼─────────────┐ + ↓ ↓ ↓ + ┌─────────────┐ ┌──────────┐ ┌─────────┐ + │ Get Context │ │ Execute │ │ Analyze │ + │ (Pre-exec) │ │ Step │ │ Result │ + └──────┬──────┘ └────┬─────┘ └────┬────┘ + │ │ │ + ├─────────────→ │ (optimize) │ + │ │ │ + │ ┌──────────→│◄────────────┤ + │ │ ↓ │ + │ │ ┌─────────────┐ │ + │ │ │ Memory Tier │ │ + │ │ │ 1/2/3 │ │ + │ │ └─────────────┘ │ + │ │ │ + └───┴────────────────────────┴────→ Learn/Document + │ + ↓ + ┌───────────────────┐ + │ Continue or Retry?│ + └─────┬─────────────┘ + │ + ┌───────────┴────────────┐ + ↓ ↓ + Next Step Attempt Retry + │ (with memory + │ guidance) + │ │ + └──────────┬─────────────┘ + ↓ + Phase Complete? + │ │ + Yes ↓ No ↓ + │ Return to + Composition Step Loop + Gate + │ + ↓ + All Phases Done? + │ + Yes ↓ No + │ └─→ Next Phase + Workflow + Complete ──→ DocumentDecision + (Final) +``` + +--- + +## Memory-Skills Matrix + +### Which Activities for Which Tools + +``` + │ Planner │ Judge │ Impl │ Verifier │ Executor +─────────┼─────────┼───────┼──────┼──────────┼───────── +Create │ ✓ │ ✓ │ ✓ │ ✓ │ ✓ +Update │ ✓ │ ✓ │ ✓ │ ✓ │ ✓ +Search │ ✓ │ ✓ │ ✓ │ ✓ │ ✓ +Context │ ✓ │ ✓ │ ✓ │ ✓ │ ✓ +Learn │ ✓ │ ✓ │ ✓ │ ✓ │ ✓ +Diagnose │ ✓ │ ✓ │ ✓ │ ✓ │ ✓ +Document │ ✓ │ ✓ │ ✓ │ ✓ │ ✓ +Vault │ ✓ │ ✓ │ ✓ │ ✓ │ ✓ +Health │ ✓ │ ✓ │ ✓ │ ✓ │ ✓ +Analyze │ ✓ │ ✓ │ ✓ │ ✓ │ ✓ +``` + +### Context Availability by Phase + +``` +Phase │ L0 (Workflow) │ L1 (Task) │ L2 (Reference) +──────┼───────────────┼───────────┼──────────────── +T0-1 │ High │ Growing │ Available +T2-3 │ High │ High │ High +T4-6 │ High │ High │ Very High +T7-10 │ High │ Very High│ Very High +``` + +--- + +## Next Steps + +### Phase 1: Integration (This Sprint) +- ✅ Memory activities implemented (12 activities) +- ✅ Temporal test suite passing (23/23 tests) +- 🔄 Wire activities into RunExecutor +- 🔄 Add memory pre/post-execution hooks +- 🔄 Ingest skill YAML → memory vault + +### Phase 2: Optimization (Next Sprint) +- 🔄 Prompt optimization with context +- 🔄 Retry policy enhancement via memory +- 🔄 Budget tracking with learned limits +- 🔄 Phase composition gate improvements + +### Phase 3: Observability (2 Sprints) +- 🔄 Memory usage metrics per phase +- 🔄 Context relevance scoring +- 🔄 Skill suggestion effectiveness tracking +- 🔄 Orchestrator dashboard with memory stats + +--- + +## Summary + +Memory-driven architecture enables Poimen to: + +1. **Learn** from every execution (Tier 1 knowledge) +2. **Improve** prompts with context (Tier 2/3 lessons) +3. **Recover** from failures faster (diagnose + suggest) +4. **Document** decisions for compliance (audit trail) +5. **Organize** skills and patterns (vault by domain) +6. **Scale** across phases (cross-phase pattern reuse) + +The state machine becomes a **learning system**, not just an executor—every run improves future runs. diff --git a/TOOL_USAGE_AND_SKILLS.md b/TOOL_USAGE_AND_SKILLS.md new file mode 100644 index 0000000..9a320f0 --- /dev/null +++ b/TOOL_USAGE_AND_SKILLS.md @@ -0,0 +1,585 @@ +# Tool Usage & Skills Ingestion Strategy + +## Poimen Tool Landscape + +### Category 1: Workflow Definition Tools + +**Tool**: `WorkflowDef Builder` (Rust) +```rust +let workflow = WorkflowDef::builder() + .name("poimen") + .phase(T0::phases())? + .step(StepId::from("T0.1-identity"))? + .transition_to(StepId::from("T0.2-kernel"))? + .build()?; +``` + +**Skill Usage**: +- Know when to use builder vs YAML +- Understand phase dependencies +- Handle schema version mismatches + +**Memory Integration**: +``` +IngestActivity { + level: "L2", + title: "WorkflowDef Builder Pattern", + content: "Use builder for Rust workflows. YAML for runtime customization.", + tags: ["T3-canonicalization", "IR"], +} +``` + +--- + +### Category 2: State Machine Tools + +**Tool**: `Event Log` (immutable JSONL) +``` +{"attempt_id": "1", "step": "T0.1", "event": "WorkerEvent::Started"} +{"attempt_id": "1", "step": "T0.1", "event": "WorkerEvent::Completed"} +{"attempt_id": "1", "step": "T0.2", "event": "WorkerEvent::Attempted"} +``` + +**Skills**: +- Event log format and ordering +- Atomic commit protocol for writes +- Fold + re-derive pattern + +**Memory Integration**: +``` +SearchActivity { + query: "event log corruption recovery", + returns: ["Verify checksum", "Replay from marker", "Fork + rewind"] +} +``` + +**Tool**: `Fold & Re-derive` +```rust +fn fold_state(state: &mut AttemptState, event: &WorkerEvent) { + match event { + WorkerEvent::Started => state.status = Running, + WorkerEvent::Completed => state.status = Success, + // ... + } +} +``` + +**Skills**: +- Deterministic state transitions +- No side effects in fold +- Time-ordered replay + +**Memory Integration**: +``` +DiagnoseIssueActivity { + issue: "state divergence after event log replay", + returns: [ + "Tier 1: Check for non-deterministic fold", + "Tier 2: Verify event order", + "Tier 3: See fold/re-derive docs" + ] +} +``` + +--- + +### Category 3: Execution Tools + +**Tool**: `Run Executor` (polling) +```rust +loop { + let task = queue.wait_for_task(timeout)?; + let output = executor.execute_step(&task)?; + queue.mark_complete(&task, &output)?; +} +``` + +**Skills**: +- Long-poll timeouts +- Task queue semantics +- Backpressure handling + +**Memory Integration**: +``` +IngestActivity { + level: "L1", + title: "Executor Timeout Pattern", + content: "20s task queue poll, 30s step timeout, exponential backoff", + tags: ["executor", "T1-execution"], +} +``` + +**Tool**: `Attempt Lifecycle` +```rust +pub struct AttemptState { + number: u32, // 1st, 2nd, 3rd attempt + started_at: SystemTime, + budget: Budget, // tokens, attempts, time + context: PartitionedContext, // input for this attempt + retry_policy: RetryPolicy, +} +``` + +**Skills**: +- Budget exhaustion detection +- Retry condition evaluation +- Context capture per attempt + +**Memory Integration**: +``` +ContextActivity { + tool: "executor", + task: "attempt-lifecycle", + returns: { + tier_1: "Known budget limits per phase", + tier_2: "Learned attempt success rates", + tier_3: "Docs on RetryPolicy tuning", + } +} +``` + +--- + +### Category 4: Verification Tools + +**Tool**: `Verifier Port` (pluggable) +```rust +pub trait Verifier { + fn verify(&self, output: &Output, rubric: &Rubric) -> Result; +} +``` + +**Skills**: +- Rubric definition (JSON/YAML) +- Verification logic chains +- Failure categorization + +**Memory Integration**: +``` +SearchActivity { + query: "rubric evaluation patterns", + returns: [ + "Multi-level rubric structure", + "Failure classification system", + "Score aggregation methods" + ] +} +``` + +**Tool**: `Judge Port` (decision logic) +```rust +pub trait Judge { + fn decide(&self, attempt: &AttemptState) -> Decision; + // → Approve | Reject | RequestRevision | Retry +} +``` + +**Skills**: +- Decision thresholds +- Evidence combination +- Feedback injection + +**Memory Integration**: +``` +DiagnoseIssueActivity { + issue: "judge consistently rejects step output", + returns: [ + "Tier 1: Check rubric alignment", + "Tier 2: Review judge logic history", + "Tier 3: See judge tuning guide" + ] +} +``` + +--- + +### Category 5: Model Provider Tools + +**Tool**: `ModelProvider Port` +```rust +pub trait ModelProvider { + fn run(&self, model_id: &str, prompt: &str, budget: &Budget) -> Result; +} +``` + +**Skills**: +- Model selection (when to use which model) +- Prompt engineering +- Token budgeting +- Error handling per model + +**Memory Integration - Prompt Optimization**: +``` +GetContextActivity { + tool: "model-provider", + task: "planner-step-generation", + returns: { + tier_1: "Known failure patterns for this step", + tier_2: "Successful prompt patterns", + tier_3: "Model capability guide", + } +} +// Use returned context to optimize prompt: +optimized_prompt = inject_learned_lessons( + base_prompt, + context.lessons, // "Always include edge cases for T1.3" + context.skills, // "Skill: planning-with-constraints" +) +``` + +**Skill Example: Prompt Template**: +```yaml +title: "Planner Step with Constraint Handling" +level: "L2" +content: | + You are a step planner for workflow execution. + + # Constraints (learned): + - Never generate steps without verification steps + - Include retry limits in plan + - Budget awareness required + + # Examples from memory (tier-2): + - Previous successful T1.3 outputs show pattern X + - Failed attempts shared pattern Y to avoid + + # Instructions: + Generate plan with these considerations... +``` + +--- + +### Category 6: Storage Tools + +**Tool**: `EventLog Port` (redb implementation) +```rust +pub trait EventLog { + fn append(&mut self, event: WorkerEvent) -> Result; + fn read(&self, range: Range) -> Result>; +} +``` + +**Skills**: +- Event serialization format +- Atomic writes +- Recovery from incomplete commits + +**Memory Integration**: +``` +LearnFromExecutionActivity { + taskID: "T0.5-eventlog-persistence", + result: "Redb backend successfully persisted 10K events", + tags: ["storage", "T0", "persistence"] +} +``` + +**Tool**: `BlobStore Port` (prompt/output capture) +```rust +pub trait BlobStore { + fn write(&self, path: &str, data: &[u8]) -> Result<()>; + fn read(&self, path: &str) -> Result>; +} +``` + +**Skills**: +- Path conventions (/{attempt_id}/{step_id}/prompt.txt) +- Compression strategies +- Retention policies + +**Memory Integration**: +``` +DocumentDecisionActivity { + decisionType: "blob-retention", + decision: "Archive attempts > 30 days to cold storage", + reasoning: "Balance audit trail with cost" +} +``` + +--- + +## Skills Ingestion Strategy + +### Phase 1: YAML Skills Registry + +**File**: `prompts/skills.yaml` +```yaml +skills: + - id: "kernel-state-machine" + category: "T0-kernel" + level: "L2" + title: "State Machine Kernel Patterns" + content: | + Key patterns for T0: + - Event log append-only design + - Atomic commit with 2PC + - Fold determinism for state derivation + - Fork/rewind for attempt recovery + + - id: "attempt-lifecycle" + category: "T1-execution" + level: "L2" + title: "Attempt Lifecycle Management" + content: | + Execution loop patterns: + - Poll-based task queue + - Budget tracking (tokens, attempts, time) + - Retry policy evaluation + - Context capture per attempt + + - id: "prompt-optimization" + category: "model-provider" + level: "L2" + title: "Memory-Based Prompt Optimization" + content: | + Best practices: + - Retrieve 3-tier context before execution + - Inject learned facts from tier-1 (exact matches) + - Include tier-2 patterns (ML-similar) + - Reference tier-3 docs (general guidance) + - Set budget constraints from experience +``` + +### Phase 2: Ingest Skills on Startup + +```go +// In cmd/starter/main.go + +func ingestSkills(memSvc *memory.Service) error { + skillsYAML, err := ioutil.ReadFile("prompts/skills.yaml") + if err != nil { + return err + } + + var skillsConfig struct { + Skills []struct { + ID string `yaml:"id"` + Category string `yaml:"category"` + Level string `yaml:"level"` + Title string `yaml:"title"` + Content string `yaml:"content"` + } `yaml:"skills"` + } + + if err := yaml.Unmarshal(skillsYAML, &skillsConfig); err != nil { + return err + } + + for _, skill := range skillsConfig.Skills { + _, err := memSvc.CreateKnowledge(ctx, &memory.KnowledgeRecord{ + Level: skill.Level, + Title: skill.Title, + Content: skill.Content, + Source: fmt.Sprintf("skills:///%s", skill.ID), + Metadata: map[string]interface{}{ + "skill_id": skill.ID, + "category": skill.Category, + "type": "skill", + }, + }) + if err != nil { + log.Warn(fmt.Sprintf("Failed to ingest skill %s: %v", skill.ID, err)) + continue + } + log.Info(fmt.Sprintf("Ingested skill: %s", skill.Title)) + } + + return nil +} +``` + +### Phase 3: Reference Docs Ingestion + +**File**: `poimen/crates/doc/` (Rust doc comments) + +```rust +/// # Attempt Lifecycle Pattern +/// +/// Every step execution follows this sequence: +/// 1. Check budget (tokens, attempts, time remaining) +/// 2. Retrieve context from memory (3-tier) +/// 3. Optimize prompt with lessons & skills +/// 4. Execute with ModelProvider +/// 5. Evaluate with Verifier +/// 6. Decide with Judge +/// 7. Learn (success) or Diagnose (failure) +/// 8. Retry or proceed to next step +/// +/// # Budget Tracking +/// - Tokens: Count LLM input/output tokens +/// - Attempts: Number of retries allowed +/// - Time: Wall-clock timeout per step +/// +/// # Retry Policy +/// - Exponential backoff: 1s → 2s → 4s +/// - Max attempts: 3 (configurable) +/// - Non-retryable: Syntax errors, auth failures +pub struct AttemptState { ... } +``` + +**Ingest Docs**: +```go +// Extract doc comments and ingest as L2 knowledge +// Run during build/startup: +// $ cargo doc --extract-comments | memory-ingest --level L2 +``` + +### Phase 4: Execution Pattern Capture + +```go +// In RunExecutor::execute_step() + +func (e *Executor) execute_step(ctx *WorkflowContext, step *StepId) error { + // ... execution logic ... + + // Capture pattern on success + if output.status == Success { + memSvc.CreateKnowledge(ctx, &memory.KnowledgeRecord{ + Level: "L1", + Title: fmt.Sprintf("Successful %s execution", step), + Content: fmt.Sprintf( + "Step %s completed with output:\n%s", + step, output.text, + ), + Source: fmt.Sprintf("workflow://execution/%s", step), + Metadata: map[string]interface{}{ + "step_id": step.String(), + "phase": ctx.PhaseId, + "attempt": ctx.AttemptState.Number, + "tokens_used": output.tokens, + }, + }) + } +} +``` + +--- + +## Tool-Skill Mapping Matrix + +``` +┌────────────────────────────────────────────────────────────────┐ +│ Tool → Skill Dependencies │ +├──────────────────────┬──────────────────────────────────────────┤ +│ Tool │ Skills Needed (from memory) │ +├──────────────────────┼──────────────────────────────────────────┤ +│ WorkflowDef Builder │ • Phase dependencies │ +│ │ • IR canonicalization rules │ +│ │ • Schema versioning │ +├──────────────────────┼──────────────────────────────────────────┤ +│ Event Log │ • Event ordering guarantees │ +│ │ • Atomic commit protocol │ +│ │ • Checksum validation │ +├──────────────────────┼──────────────────────────────────────────┤ +│ Run Executor │ • Attempt lifecycle patterns │ +│ │ • Budget exhaustion detection │ +│ │ • Retry policy evaluation │ +├──────────────────────┼──────────────────────────────────────────┤ +│ Verifier Port │ • Rubric structure design │ +│ │ • Failure categorization │ +│ │ • Score aggregation rules │ +├──────────────────────┼──────────────────────────────────────────┤ +│ Judge Port │ • Decision thresholds │ +│ │ • Evidence combination logic │ +│ │ • Feedback injection patterns │ +├──────────────────────┼──────────────────────────────────────────┤ +│ ModelProvider │ • Prompt engineering best practices │ +│ │ • Token budget awareness │ +│ │ • Model-specific quirks │ +├──────────────────────┼──────────────────────────────────────────┤ +│ EventLog Storage │ • Serialization format choices │ +│ │ • Compression strategies │ +│ │ • Recovery procedures │ +├──────────────────────┼──────────────────────────────────────────┤ +│ BlobStore │ • Path naming conventions │ +│ │ • Retention policies │ +│ │ • Archive triggers │ +└──────────────────────┴──────────────────────────────────────────┘ +``` + +--- + +## Basic Tool Usage Example + +### Scenario: Planner Step Fails Repeatedly + +**User Command**: +```bash +poimen plan my-workflow.yaml --phase T1 --retry-with-memory +``` + +**Tool Execution Chain**: + +``` +1. LOAD WORKFLOW + WorkflowDefBuilder.from_yaml("my-workflow.yaml") + → Memory: Retrieve "IR-canonicalization" skills + → Validate against stored L2 knowledge + +2. INIT EXECUTOR + RunExecutor.new() + → Memory: Get "attempt-lifecycle" context + → Load retry policy from memory lessons + +3. EXECUTE PLANNER STEP + for attempt in 1..max_attempts: + a) GetContextActivity + - Tool: "planner" + - Task: "step-generation" + - Returns: lessons + skills + + b) OptimizePrompt + - Inject learned facts (tier-1) + - Add pattern examples (tier-2) + - Set budget from history + + c) ModelProvider.run(optimized_prompt) + - Send to planner agent + - Wait for output + + d) Verifier.verify(output) + - Check against rubric + - Score output quality + + e) Judge.decide(output) + - Approve | Retry | Reject + + f) On Success: LearnFromExecutionActivity + - Store successful output pattern (L1) + + g) On Failure: AnalyzeErrorActivity + - Search for similar failures + - Return recovery suggestions + + h) DocumentDecisionActivity + - Log decision and reasoning + +4. COMPLETED + ✅ Plan generated (or user feedback required) + → Memory: Ingest execution pattern + → Next phase starts +``` + +--- + +## Summary: Tool & Skill Flow + +``` +Workflow Execution + ↓ + Tools Used ────────────────→ Skills Retrieved from Memory + ├─ WorkflowDefBuilder ├─ IR canonicalization rules + ├─ EventLog ├─ State machine patterns + ├─ RunExecutor ├─ Attempt lifecycle + ├─ Verifier Port ├─ Rubric design + ├─ Judge Port ├─ Decision logic + ├─ ModelProvider ├─ Prompt optimization + └─ Storage Ports └─ Retention policies + + Skills Guide Execution ──────→ Results Learned + ├─ Success patterns (L1) + ├─ Failure recovery (L1) + ├─ Verified practices (L2) + └─ Vault enriched for next run +``` + +This creates a **virtuous cycle**: Each execution improves the memory, which improves the next execution. diff --git a/k8s/git-commit.yaml b/k8s/git-commit.yaml index d014bea..a238050 100644 --- a/k8s/git-commit.yaml +++ b/k8s/git-commit.yaml @@ -9,6 +9,6 @@ metadata: app.kubernetes.io/name: poimen app.kubernetes.io/component: orchestrator data: - GIT_COMMIT: "c2df8a0" # Updated automatically by CI/CD + GIT_COMMIT: "4982c04" # Updated automatically by CI/CD GIT_BRANCH: "main" DEPLOYMENT_DATE: "2026-08-29" diff --git a/k8s/worker-deployment.yaml b/k8s/worker-deployment.yaml index d5d4b8d..7288a73 100644 --- a/k8s/worker-deployment.yaml +++ b/k8s/worker-deployment.yaml @@ -13,7 +13,7 @@ spec: labels: app: poimen-worker annotations: - git-commit: "c2df8a0" # ✅ Updated on each push, triggers rolling restart + git-commit: "4982c04" # ✅ Updated on each push, triggers rolling restart deployment-date: "2026-08-29" spec: containers: