Ai Agents Improvements Explained
Ecosistema completo para organización y gestión de contenido con interfaces espaciales
🧠 AI Agent Self-Learning System - Concepts Explained
This document explains why we need each component and how they work together to create a self-learning AI system.
Table of Contents
- The Problem We're Solving
- What Are Vector Embeddings?
- Why MongoDB Vector Search?
- What Are Embeddings APIs?
- Multi-Provider Support (OpenAI, Anthropic, etc.)
- What Is Pattern Mining?
- Confidence Calibration Explained
- How It All Works Together
- Frontend Monitoring Dashboard
The Problem We're Solving
Current State: AI Has Amnesia
Every time you start a new conversation with Claude or ChatGPT, it starts completely fresh. It doesn't remember:
- What worked before
- What didn't work
- Your preferences
- Patterns that led to success
- Mistakes to avoid
Session 1: "Build auth with JWT" → AI figures it out from scratch
Session 2: "Build auth with JWT" → AI figures it out from scratch AGAIN
Session 3: "Build auth with JWT" → AI figures it out from scratch AGAIN!
This is wasteful. Each session, the AI is essentially "starting over."
Goal: AI That Learns and Remembers
We want:
Session 1: "Build auth with JWT" → AI figures it out, SAVES what worked
Session 2: "Build auth with JWT" → AI RECALLS past success, applies immediately
Session 3: "Build auth with JWT" → AI is now EXPERT at this, instant success
What Are Vector Embeddings?
The Concept: Meaning as Numbers
The Problem: Computers understand numbers, not meaning.
- "Dog" and "Puppy" look completely different as text
- But they MEAN almost the same thing
The Solution: Vector Embeddings
An embedding converts text into a list of numbers (a "vector") that captures its meaning.
"Dog" → [0.23, -0.45, 0.89, 0.12, ..., 0.56] (1536 numbers)
"Puppy" → [0.21, -0.43, 0.91, 0.14, ..., 0.58] (1536 numbers)
"Car" → [-0.78, 0.32, -0.15, 0.67, ..., -0.23] (1536 numbers)
Notice:
- "Dog" and "Puppy" have SIMILAR numbers (they mean similar things)
- "Car" has DIFFERENT numbers (it means something different)
Visual Analogy
Think of it like GPS coordinates:
"Dog" → Location: (23.5, -45.2)
"Puppy" → Location: (23.7, -44.8) ← Very close! Similar meaning
"Car" → Location: (-78.1, 32.4) ← Far away! Different meaning
Why Is This Powerful?
We can now search by meaning, not just keywords:
Traditional Search: "How to authenticate users?"
→ Only finds docs containing exact words "authenticate" and "users"
Semantic Search (with embeddings): "How to authenticate users?"
→ Finds: "User login implementation"
→ Finds: "JWT token validation"
→ Finds: "Auth middleware setup"
→ ALL related, even without matching words!
How We Use This
When AI makes a decision:
- We embed the decision text → Get a vector
- Store the vector in the database
- Later, when facing a similar problem:
- Embed the new problem → Get a query vector
- Find vectors that are "close" (similar meaning)
- Retrieve those past successful decisions!
Why MongoDB Vector Search?
The Challenge: Finding Similar Vectors FAST
We might have millions of embedded decisions. Finding similar ones by:
- Comparing to every single one? Way too slow!
- Traditional database index? Doesn't work for vectors
Solution: Vector Search Index
MongoDB Atlas Vector Search creates a special index that:
- Organizes vectors in a "tree" structure
- Enables finding similar vectors in milliseconds
- Even among millions of vectors
// Example: Find decisions similar to "How should I handle user authentication?"
db.agent_embeddings.aggregate([
{
$vectorSearch: {
index: "decision_vector_index",
queryVector: [0.23, -0.45, ...], // Embedding of the question
path: "embedding",
numCandidates: 100,
limit: 5
}
}
])
// Returns: 5 most similar past decisions in ~10ms!
Why Not Just Use Regular MongoDB?
| Approach | 1M Documents | Speed |
|---|---|---|
| Brute Force (compare all) | 1 million comparisons | ~30 seconds |
| Vector Search Index | ~100 comparisons | ~10ms |
Vector Search is 3000x faster!
Alternatives to MongoDB Atlas Vector Search
| Solution | Pros | Cons |
|---|---|---|
| MongoDB Atlas | Already using MongoDB, integrated | Requires M10+ tier |
| Pinecone | Purpose-built for vectors | Another service to manage |
| Weaviate | Open source, powerful | Separate infrastructure |
| pgvector | PostgreSQL extension | Requires PostgreSQL |
| Chroma | Simple, local | Not for production scale |
We chose MongoDB because you're already using it, and it keeps everything in one place.
What Are Embeddings APIs?
The Service: Text → Numbers
Embedding APIs take text and return vectors. Multiple providers offer this:
OpenAI Embeddings
// Request
POST https://api.openai.com/v1/embeddings
{
"model": "text-embedding-3-small",
"input": "How should I implement user authentication?"
}
// Response
{
"data": [{
"embedding": [0.023, -0.045, 0.089, ..., 0.056] // 1536 numbers
}]
}
Models Available:
| Model | Dimensions | Cost per 1M tokens | Best For |
|---|---|---|---|
text-embedding-3-small |
1536 | $0.02 | General use (recommended) |
text-embedding-3-large |
3072 | $0.13 | Higher accuracy |
text-embedding-ada-002 |
1536 | $0.10 | Legacy |
Why OpenAI?
- Industry standard
- Very accurate
- Simple API
- Affordable (~$5 for 100K decisions)
Multi-Provider Support
Yes! We Can Use Multiple Providers
You asked if we can use Anthropic too. Absolutely! Here's how:
Anthropic (Claude) - Coming Soon
Anthropic doesn't currently offer a public embeddings API, BUT:
- They're expected to release one
- We can use their chat API to generate pseudo-embeddings
- We've designed the system to be provider-agnostic
Other Embedding Providers
| Provider | API | Dimensions | Notes |
|---|---|---|---|
| OpenAI | text-embedding-3-small |
1536 | Best general choice |
| Cohere | embed-english-v3.0 |
1024 | Good for code |
| Vertex AI Embeddings | 768 | Part of GCP | |
| Voyage AI | voyage-code-2 |
1536 | Specialized for code |
| HuggingFace | Various models | Varies | Open source options |
| Local Models | all-MiniLM-L6-v2 |
384 | Free, runs locally |
How We Support Multiple Providers
// Our service is provider-agnostic
interface EmbeddingProvider {
name: string;
generateEmbedding(text: string): Promise<number[]>;
dimensions: number;
}
// We can add any provider
const providers: Record<string, EmbeddingProvider> = {
openai: new OpenAIEmbeddingProvider(),
cohere: new CohereEmbeddingProvider(),
voyage: new VoyageEmbeddingProvider(),
local: new LocalEmbeddingProvider(), // HuggingFace model running locally
};
// Use configured provider
const embedding = await providers[configuredProvider].generateEmbedding(text);
Recommendation
Start with OpenAI text-embedding-3-small:
- Most reliable
- Good quality
- Low cost
- Easy to switch later if needed
What Is Pattern Mining?
The Concept: Learning Rules from Examples
Imagine you have 1,000 successful coding decisions. Pattern mining finds common patterns among them.
Example
Raw Decisions (stored in database):
Decision 1: "Use Signals for component state" → Rating: 5/5
Decision 2: "Use Signals for local reactive values" → Rating: 5/5
Decision 3: "Use Signals instead of BehaviorSubject" → Rating: 4/5
Decision 4: "RxJS BehaviorSubject for component state" → Rating: 2/5
Decision 5: "Signals for UI state management" → Rating: 5/5
Pattern Mining Output:
Pattern Discovered:
Name: "Use Signals for Local State"
Context: When managing component-local reactive state
Recommendation: Use Angular Signals instead of RxJS
Reasoning: Simpler API, better change detection integration
Success Rate: 93%
Support: 4 decisions
How It Works
Cluster Similar Decisions
- Group decisions that are semantically similar (using embeddings)
- "Signal" decisions cluster together
Filter by Quality
- Only look at decisions with rating ≥ 4/5
- We want to learn from SUCCESS, not failure
Extract Generalization
- Use AI to find the common pattern
- "What do these successful decisions have in common?"
Calculate Confidence
- More examples = higher confidence
- Higher ratings = higher confidence
- More recent = slightly higher weight
What We Do With Patterns
Inject into AI Prompts:
When starting a new coding task, we tell the AI:
## Learned Patterns from Past Success
### Pattern: Use Signals for Local State
When: Managing component-local reactive state
Do: Use Angular Signals instead of RxJS
Why: Simpler API, better change detection integration
Success Rate: 93% (based on 50+ decisions)
### Pattern: Validate at Boundaries
When: Accepting external input (API, user)
Do: Use Zod schemas for runtime validation
Why: Type-safe, excellent error messages
Success Rate: 89% (based on 30+ decisions)
---
Apply these patterns when relevant.
Now the AI starts with knowledge instead of figuring things out from scratch!
Confidence Calibration Explained
The Problem: AI Can Be Overconfident
AI might say "I'm 90% confident this is right" but actually only be right 60% of the time.
AI Prediction: "90% confident" → Actually correct: 60%
AI Prediction: "80% confident" → Actually correct: 50%
AI Prediction: "70% confident" → Actually correct: 65%
This is called miscalibration.
The Solution: Track and Adjust
We track:
- What AI predicted (confidence level)
- What actually happened (user rating)
- The difference (calibration offset)
// Example calibration data
{
decisionType: "implementation-choice",
agentType: "executor",
taskType: "vibe-coding",
// Historical data shows...
avgPredictedConfidence: 0.85, // AI says "85% confident"
avgActualOutcome: 0.70, // But actually right 70% of time
calibrationOffset: +0.15, // Overconfident by 15%
}
How We Use It
When AI makes a new decision:
// AI's raw confidence
const rawConfidence = 0.90; // "90% confident"
// Look up calibration for this type
const calibration = getCalibration("implementation-choice", "executor");
// calibration.offset = +0.15 (historically overconfident)
// Apply calibration
const calibratedConfidence = rawConfidence - calibration.offset;
// = 0.90 - 0.15 = 0.75
// Tell AI: "Your adjusted confidence is 75%, not 90%"
Over time, the AI learns to be accurately confident - not over or under.
How It All Works Together
The Complete Flow
┌─────────────────────────────────────────────────────────────────────────────┐
│ SELF-LEARNING AI SYSTEM │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ USER REQUEST: "Build a login form with validation" │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ 1. CONTEXT ENHANCEMENT │ │
│ │ • Embed the request → Get query vector │ │
│ │ • Search Vector Memory → Find similar past decisions │ │
│ │ • Retrieve relevant patterns │ │
│ │ • Get calibration data │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ 2. ENHANCED PROMPT TO AI │ │
│ │ │ │
│ │ "Build a login form with validation" │ │
│ │ │ │
│ │ ## Similar Past Decisions (Successful): │ │
│ │ - "Used Reactive Forms + Zod validation" (Rating: 5/5) │ │
│ │ - "Implemented async validators for email" (Rating: 4/5) │ │
│ │ │ │
│ │ ## Learned Patterns: │ │
│ │ - Use Zod for validation (89% success rate) │ │
│ │ - Use Reactive Forms over Template-driven (92% success) │ │
│ │ │ │
│ │ ## Calibration Note: │ │
│ │ For form-related decisions, you've been 12% overconfident. │ │
│ │ Adjust your confidence accordingly. │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ 3. AI MAKES DECISIONS │ │
│ │ • Decision: "Use Reactive Forms with Zod validation" │ │
│ │ • Reasoning: "Pattern #23 shows 89% success rate..." │ │
│ │ • Confidence: 82% (calibrated from 94%) │ │
│ │ │ │
│ │ [DECISION LOGGED + EMBEDDED] │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ 4. TASK COMPLETES │ │
│ │ • AI finishes building the form │ │
│ │ • Code delivered to user │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ 5. USER FEEDBACK │ │
│ │ "How would you rate this work?" │ │
│ │ ⭐⭐⭐⭐⭐ (5/5) │ │
│ │ "Did you modify the code?" No │ │
│ │ "Would you use again?" Yes │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ 6. LEARNING LOOP │ │
│ │ • Update decision outcome: qualityRating = 5, success = true │ │
│ │ • Update calibration: This type slightly underconfident │ │
│ │ • Pattern strength increased: "Reactive Forms + Zod" │ │
│ │ • NEXT TIME → Even better recommendations! │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
Frontend Monitoring Dashboard
What You'll Be Able to See and Control
1. Learning Dashboard Overview
┌────────────────────────────────────────────────────────────────────────────┐
│ 🧠 AI Learning Dashboard [Refresh] │
├────────────────────────────────────────────────────────────────────────────┤
│ │
│ HEALTH METRICS │
│ ┌──────────────────┬──────────────────┬──────────────────┐ │
│ │ Decisions Stored │ Patterns Active │ Avg Quality │ │
│ │ 12,847 │ 156 │ 4.2/5 ⭐ │ │
│ └──────────────────┴──────────────────┴──────────────────┘ │
│ │
│ CALIBRATION STATUS │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ implementation-choice: 🟢 Well calibrated (±8%) │ │
│ │ task-decomposition: 🟡 Slightly overconfident (+15%) │ │
│ │ error-recovery: 🔴 Needs attention (+28%) │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │
│ LEARNING TREND (Last 30 Days) │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ 📈 │ │
│ │ / \ /\ │ │
│ │ / \ / \ /\ │ │
│ │ / \/ \ / \ 📈 │ │
│ │ / \/ \/ │ │
│ │ Nov 10 Nov 17 Nov 24 Dec 1 Dec 8 │ │
│ │ │ │
│ │ — Success Rate — Pattern Usage — Confidence Accuracy │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │
└────────────────────────────────────────────────────────────────────────────┘
2. Pattern Explorer
┌────────────────────────────────────────────────────────────────────────────┐
│ 📚 Learned Patterns [Mine New] [Export]│
├────────────────────────────────────────────────────────────────────────────┤
│ │
│ Filter: [All Types ▼] [All Agents ▼] [Min Success: 70% ▼] │
│ │
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ 🏆 #1: Use Signals for Local State │ │
│ │ ──────────────────────────────────────────────────────────────────│ │
│ │ Success: 94% │ Support: 127 decisions │ Applied: 89 times │ │
│ │ Type: implementation-choice │ Status: ✅ Active │ │
│ │ │ │
│ │ When: Managing component-local reactive state │ │
│ │ Do: Use Angular Signals instead of RxJS BehaviorSubject │ │
│ │ Why: Simpler API, better change detection, less boilerplate │ │
│ │ │ │
│ │ [View Details] [Deactivate] [Edit] │ │
│ └────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ 🥈 #2: Validate at System Boundaries │ │
│ │ ──────────────────────────────────────────────────────────────────│ │
│ │ Success: 91% │ Support: 85 decisions │ Applied: 62 times │ │
│ │ Type: implementation-choice │ Status: ✅ Active │ │
│ │ │ │
│ │ When: Accepting external input (API responses, user input) │ │
│ │ Do: Use Zod schemas for runtime validation │ │
│ │ Why: Type-safe, excellent error messages, composable │ │
│ │ │ │
│ │ [View Details] [Deactivate] [Edit] │ │
│ └────────────────────────────────────────────────────────────────────┘ │
│ │
└────────────────────────────────────────────────────────────────────────────┘
3. Decision Memory Browser
┌────────────────────────────────────────────────────────────────────────────┐
│ 🔍 Decision Memory [Search] │
├────────────────────────────────────────────────────────────────────────────┤
│ │
│ Search: [authentication implementation________________] [🔍 Semantic] │
│ │
│ Found 23 similar decisions: │
│ │
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ Similarity: 94% │ Rating: 5/5 │ Date: Dec 5, 2025 │ │
│ │ ─────────────────────────────────────────────────────────────────│ │
│ │ Question: "How should I implement JWT authentication?" │ │
│ │ Chosen: "Use @libs-core/security with JWT + refresh tokens" │ │
│ │ Reasoning: "The security library already handles token refresh, │ │
│ │ storage, and provides guards. No need to reinvent..." │ │
│ │ │ │
│ │ Outcome: ✅ Successful │ Modified: No │ Task: #task-789 │ │
│ │ [View Full Decision] [View Task] [Use as Example] │ │
│ └────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ Similarity: 89% │ Rating: 4/5 │ Date: Nov 28, 2025 │ │
│ │ ─────────────────────────────────────────────────────────────────│ │
│ │ Question: "Best approach for auth in Angular?" │ │
│ │ Chosen: "JWT with HTTP interceptor for auto-attach" │ │
│ │ Reasoning: "Interceptors handle auth header automatically..." │ │
│ │ │ │
│ │ Outcome: ✅ Successful │ Modified: Yes │ Task: #task-654 │ │
│ │ [View Full Decision] [View Task] [Use as Example] │ │
│ └────────────────────────────────────────────────────────────────────┘ │
│ │
└────────────────────────────────────────────────────────────────────────────┘
4. Calibration Monitor
┌────────────────────────────────────────────────────────────────────────────┐
│ 📊 Confidence Calibration [Recalibrate All] │
├────────────────────────────────────────────────────────────────────────────┤
│ │
│ CALIBRATION BY DECISION TYPE │
│ │
│ implementation-choice │
│ Predicted: 85% │ Actual: 78% │ Offset: +7% (slightly overconfident) │
│ ████████████████████░░░░░ Samples: 234 (reliable) │
│ │
│ task-decomposition │
│ Predicted: 82% │ Actual: 65% │ Offset: +17% (overconfident ⚠️) │
│ ██████████████░░░░░░░░░░░ Samples: 89 (reliable) │
│ │
│ error-recovery │
│ Predicted: 75% │ Actual: 48% │ Offset: +27% (very overconfident 🔴) │
│ ████████░░░░░░░░░░░░░░░░░ Samples: 45 (reliable) │
│ │
│ ──────────────────────────────────────────────────────────────────── │
│ │
│ RECOMMENDATIONS: │
│ • error-recovery decisions need attention - AI is very overconfident │
│ • Consider adding more training examples for task-decomposition │
│ • implementation-choice is well calibrated ✅ │
│ │
└────────────────────────────────────────────────────────────────────────────┘
5. Training Data Export
┌────────────────────────────────────────────────────────────────────────────┐
│ 📤 Export Training Data │
├────────────────────────────────────────────────────────────────────────────┤
│ │
│ FILTER OPTIONS │
│ │
│ Date Range: [Last 30 Days ▼] │
│ Min Quality: [4/5 ⭐ ▼] │
│ Include: [✓] Decisions [✓] Patterns [ ] Failed tasks │
│ Format: [JSONL ▼] │
│ │
│ PREVIEW │
│ ─────── │
│ Matching: 1,247 decisions, 156 patterns │
│ Estimated size: 4.2 MB │
│ │
│ Sample record: │
│ { │
│ "question": "How to handle form validation?", │
│ "chosen": "Use Reactive Forms with Zod", │
│ "reasoning": "Provides type safety and...", │
│ "quality_rating": 5, │
│ "was_successful": true │
│ } │
│ │
│ [Preview More] [Export] │
│ │
└────────────────────────────────────────────────────────────────────────────┘
Dashboard Features Summary
| Feature | What It Does | Why It Matters |
|---|---|---|
| Overview | Health metrics at a glance | Quick status check |
| Pattern Explorer | View, edit, activate/deactivate patterns | Control what AI learns |
| Decision Browser | Search past decisions semantically | Find relevant precedents |
| Calibration Monitor | Track AI confidence accuracy | Identify overconfidence |
| Training Export | Export data for model fine-tuning | External training |
| Real-time Updates | WebSocket live updates | Monitor as AI works |
Summary: What We're Building
| Component | What It Is | Why We Need It |
|---|---|---|
| Vector Embeddings | Numbers that capture meaning | Enable semantic search |
| MongoDB Vector Search | Fast similarity lookup | Find relevant past decisions quickly |
| Embedding API | Service that creates embeddings | Convert text to vectors |
| Pattern Mining | Extract rules from successes | Teach AI proven approaches |
| Confidence Calibration | Track prediction accuracy | Make AI honestly confident |
| Monitoring Dashboard | Visual control center | See, control, and export everything |
Next Steps
Now that you understand the concepts:
Set Up Infrastructure
- MongoDB Atlas Vector Search
- OpenAI API key for embeddings
Build Monitoring Dashboard
- Pattern Explorer
- Decision Browser
- Calibration Monitor
- Training Data Export
Wire Up Integration
- Connect to vibe-coding interface
- Auto-embed decisions
- Feedback collection
Start Learning!
- System improves with every task
- Patterns emerge automatically
- AI gets smarter over time
Questions? This document will be updated as the system evolves.
Last Updated: December 2025