Agentic Context Engineering and Reflections in Claudiomiro

November 30, 2025 · View on GitHub

This guide describes how Claudiomiro assembles execution context and learns across iterations. Agentic Context Engineering builds precise prompts while the reflection pipeline extracts lessons that feed future tasks.

Overview

  • Agentic Context Engineering collects, compresses, and distributes only the most relevant information for every step (src/shared/services/context-cache). It tracks execution history, indexes the codebase, and saves tokens by trimming noise.
  • Reflections review each run to capture actionable insights (src/shared/services/reflection, src/commands/task-executor/steps/step5/reflection-hook.js). The results are persisted and reused later.
  • Insights Service is the shared memory for curated patterns and reflections (src/shared/services/insights/insight-store.js). Claudiomiro surfaces these insights automatically in future prompts.

Together they create a loop: task → execution → reflection → insights → optimized context → next task.

Agentic Context Architecture

Core building blocks

  • context-cache/ handles incremental cache, summaries, and invalidation (stored in .claudiomiro/cache/context-cache.json).
  • code-index/ maintains a semantic symbol index so prompts reference precise code instead of entire files.
  • local-llm/ (optional) powers local summarization and topic detection to cut 40–60% of token usage whenever a local model is available.
  • insights/ unifies curated patterns (global + project) and reflection history.

Step-by-step data flow

  1. Step 4 – Generate TODO (src/commands/task-executor/steps/step4/generate-todo.js)
    • Calls buildOptimizedContextAsync, which blends:
      • the cached AI_PROMPT.md summary,
      • completed tasks with files/decisions,
      • relevant symbols from the code index,
      • curated insights from previous runs.
    • The resulting prompt snippet keeps content short and lists only file references that the agent can open if needed.
  2. Step 5 – Execute Task (src/commands/task-executor/steps/step5/index.js)
    • After executing the plan, Claudiomiro writes CONTEXT.md and invokes markTaskCompleted to refresh the incremental cache.
    • Execution metrics (attempts, errors, change size, complexity) drive the reflection trigger.
  3. Step 6 – Curate Insights (src/commands/task-executor/steps/step6/curate-insights.js)
    • Aggregates patterns from TODO/CONTEXT/CODE_REVIEW/REFLECTION.
    • Persists the best entries with scope classification so they can guide future tasks automatically.

Context tactics

  • Incremental cache: only tasks marked as “Fully implemented: YES” contribute to the consolidated context. Changing AI_PROMPT.md invalidates the summary automatically.
  • LLM-assisted optimization: when CLAUDIOMIRO_LOCAL_LLM is set, the local service scores relevance and produces targeted summaries per file.
  • Code index integration: buildConsolidatedContextAsync includes high-signal symbols (functions, components, hooks) pulled via semantic search with Ollama, falling back to keyword lookup if needed.
  • Multi-repository awareness: task scopes (e.g., @scope backend) ensure each summary and index query runs inside the correct repo, preventing cross-talk between projects.

Reflection Pipeline

Trigger logic

shouldReflect (in reflection-hook.js) checks heuristics before running the reflection loop:

  • multiple attempts (attempts >= 2),
  • repeated errors,
  • large code diffs (codeChangeSize > 500),
  • TODO marked as high complexity.

Reflection execution

  • buildReflectionTrajectory assembles a dossier with TODO, CONTEXT, RESEARCH, and additional notes.
  • Reflector (src/shared/services/reflection/reflector.js) drives iterative reflection using executeClaude:
    1. Fills the template prompts/reflect-on-trajectory.md with task data, trajectory, and prior insights.
    2. Extracts structured insights via insight-extractor, falling back to pattern heuristics where necessary.
    3. Deduplicates, measures convergence (novelty, average confidence, actionable ratio), and tracks iteration history.
    4. Rewrites REFLECTION.md with the latest iteration content.

Persistence and reuse

  • storeReflection saves the iteration payload in .claudiomiro/insights/reflections/<TASK>.json, keeping a chronological record.
  • Step 6 reloads the JSON (plus the raw markdown) to generate new curated insights.
  • The insights service categorizes each entry, updates usage metrics, and exposes them through getCuratedInsightsForTask, which feeds right back into Step 4.

Impact on future runs

  • Reflection-derived action items (e.g., “add integration tests”) appear in the CURATED INSIGHTS TO CONSIDER section of subsequent TODOs.
  • When a task reruns, the reflector seeds itself with the last known insights to avoid repeating the same suggestions.

Customization and Best Practices

  • Tune reflection heuristics inside shouldReflect to match the rigor your project needs.
  • Keep TODO.md and CONTEXT.md aligned with the default headings; structured parsing depends on those markers.
  • Configure CLAUDIOMIRO_LOCAL_LLM to unlock context optimization and topic classification for RESEARCH.md.
  • When the code index feels stale, delete ./.claudiomiro/cache/code-index.json (or run the CLI command that calls CodeIndex.build(..., { forceRebuild: true })) before the next task.
  • Keep AI_PROMPT.md current; it’s the anchor for pattern detection and automatically refreshes the cache whenever it changes.

With these systems working together, Claudiomiro continuously learns from prior work, produces sharper prompts, and slashes token consumption without losing historical awareness.