Archetype System
The Archetype System wraps the existing Collective Best Practices (CBP) injection engine with Jungian archetype filtering. Every pattern injected into your session is classified into one of four archetypes and scored based on your current context, ensuring the most relevant patterns rise to the top.
Archetype classification is fully deterministic — no LLM calls are made. Context fields (outcome, observation type, consecutive failures) are mapped directly to archetype weights using a fixed algorithm.
The Four Archetypes
Shadow
Sage
Hero
Trickster
Label: Shadow WarningThe Shadow represents the hidden or unconscious negative side — things that can go wrong if you are not careful.Pattern Types:
anti_pattern — Common mistakes to avoidsecurity_warning — Security vulnerabilities and risksgotcha — Surprising behaviors that catch developers off-guard
When Dominant: Error/failure contexts. When a tool call fails, Shadow patterns are boosted (1.2x multiplier) to surface warnings about what went wrong.Example: “NEVER run git push --force to main without checking CI status first — caused production data loss for 3 teams.” Label: Sage AdviceThe Sage is the wise guide — proven solutions, best practices, and accumulated knowledge.Pattern Types:
best_practice — Proven approaches that work wellerror_solution — Known fixes for common errorsperformance_tip — Optimization recommendationsmigration_note — Version upgrade guidance
When Dominant: Default state. Sage is the primary archetype for knowledge sharing, weighted at 0.5 in the absence of other signals. Also boosted (1.1x) during error contexts alongside Shadow.Example: “Always run pnpm db:generate before pnpm db:migrate when changing the Drizzle schema — skipping generate leads to empty migrations.” Label: Hero PathThe Hero is the active doer — step-by-step workflows, tool sequences, and migration paths.Pattern Types:
workflow — Multi-step processestool_sequence — Optimal tool orderingmigration_note — Step-by-step upgrade guides
When Dominant: Workflow and tool-call contexts. When you are actively using tools or following a multi-step process, Hero patterns are prioritized (weight 0.5).Example: “Deploy workflow: 1) Run tests 2) Build Docker image 3) Push to registry 4) Apply Kubernetes manifests 5) Verify health endpoint.” Label: Trickster InsightThe Trickster is the unexpected disruptor — creative solutions, edge cases, and workarounds for when conventional approaches fail.Pattern Types:
gotcha — Edge cases and unexpected behaviorscompatibility — Version compatibility trapserror_recovery — Creative recovery strategies
When Dominant: After 2+ consecutive failures. When normal approaches keep failing, the Trickster surfaces unconventional solutions that might break through the impasse.Example: “If npm install keeps failing with EACCES, try npm cache clean --force then install with --prefer-offline — the cache corruption is the real issue.” How Weight Calculation Works
Archetype weights are determined by a fixed algorithm that examines context fields. No machine learning or LLM is involved.
Weight Selection Rules
All weights are shown after normalization (each row sums to 1.0):
Context | Shadow | Sage | Hero | Trickster
-------------------------|--------|------|------|----------
Default (no signals) | 0.10 | 0.50 | 0.30 | 0.10
Error / Failure | 0.43 | 0.39 | 0.09 | 0.09
Workflow / Tool Call | 0.10 | 0.30 | 0.50 | 0.10
Success | 0.10 | 0.40 | 0.40 | 0.10
2+ Consecutive Failures | 0.20 | 0.30 | 0.10 | 0.40
In error/failure contexts, Shadow receives a 1.2x boost and Sage receives a 1.1x boost before normalization. The pre-normalization values are Shadow=0.48, Sage=0.44, Hero=0.10, Trickster=0.10 (sum=1.12), which normalize to the values shown above.
score = archetypeWeight * confidence * similarity
- archetypeWeight: From the context-based weight table above (0.0-1.0)
- confidence: The pattern’s CBP confidence score (0.0-1.0)
- similarity: Vector similarity between the query and the pattern (0.0-1.0)
Patterns are sorted by this composite score in descending order, then capped at 2 patterns per archetype and a global maximum (default: 5 total).
Input Context
The archetype router accepts these optional context fields:
interface ArchetypeContext {
observationType?: string; // e.g., 'tool_call', 'error_pattern', 'workflow_step'
outcome?: string; // 'success', 'failure', or undefined
toolName?: string; // MCP tool name
errorMessage?: string; // Error text for post-error suggestions
consecutiveFailures?: number; // Count of back-to-back failures
query?: string; // Free-text search query
}
API Reference
Archetype-Enhanced Pattern Search
POST /api/memory/archetype/inject
Authorization: Bearer <api_key>
Content-Type: application/json
{
"query": "database migration failing",
"tool_name": "drizzle_migrate",
"outcome": "failure",
"error_message": "relation already exists",
"consecutive_failures": 2
}
{
"success": true,
"data": [
{
"patternType": "error_solution",
"description": "Run pnpm db:generate before db:migrate to regenerate schema diff",
"confidence": 0.85,
"similarity": 0.92,
"archetype": "sage",
"archetypeLabel": "Sage Advice",
"archetypeWeight": 0.39
},
{
"patternType": "gotcha",
"description": "Drizzle ORM skips ALTER TABLE for enum changes -- drop and recreate manually",
"confidence": 0.72,
"similarity": 0.88,
"archetype": "trickster",
"archetypeLabel": "Trickster Insight",
"archetypeWeight": 0.09
},
{
"patternType": "anti_pattern",
"description": "Never apply migrations directly to production database without testing",
"confidence": 0.91,
"similarity": 0.85,
"archetype": "shadow",
"archetypeLabel": "Shadow Warning",
"archetypeWeight": 0.43
}
]
}
SDK Usage
import { PluggedInClient } from 'pluggedinkit-js';
const client = new PluggedInClient({ apiKey: 'your-api-key' });
// Search with archetype-aware context
const result = await client.jungian.searchWithContext({
query: 'database migration failing',
toolName: 'drizzle_migrate',
outcome: 'failure',
});
for (const p of result.data) {
console.log(`[${p.archetypeLabel}] ${p.description}`);
console.log(` Score: ${(p.archetypeWeight * p.confidence * p.similarity).toFixed(3)}`);
}
pluggedin_memory_search_with_context MCP tool provides the same archetype-aware search:
| Parameter | Type | Required | Description |
|---|
query | string | Yes | Search query text |
toolName | string | No | MCP tool name for context |
outcome | string | No | "success" or "failure" |
Backward Compatibility
The archetype system is fully backward compatible:
- Existing injection API: Unchanged. If
ARCHETYPE_ENABLED=false, the standard injection engine is used and all patterns are labeled as sage by default.
- Existing patterns: All previously stored patterns continue to work. They are classified into archetypes at query time based on their
patternType field.
- Existing MCP tools:
pluggedin_cbp_query and pluggedin_cbp_feedback are unaffected.
Configuration
| Variable | Default | Description |
|---|
ARCHETYPE_ENABLED | true | Enable/disable archetype routing |
ARCHETYPE_MAX_PATTERNS_PER_TYPE | 2 | Max patterns returned per archetype |
ARCHETYPE_SHADOW_BOOST | 1.2 | Shadow weight multiplier in error contexts |
ARCHETYPE_SAGE_BOOST | 1.1 | Sage weight multiplier in error contexts |
Next Steps
