Back to CMP|

CMP Technical Documentation

v3.7.0
📖

Overview

CMP (Collective Memory Protocol) es una capa de inteligencia para agentes de IA que proporciona memoria persistente, aprendizaje cruzado entre proyectos, y colaboración multi-agente.

Objetivo Principal

Memoria Persistente

Diseño

Agent-First

Almacenamiento

Cloud-Native

Por qué existe CMP

Los asistentes de IA son poderosos pero tienen una limitación fundamental: olvidan todo cuando termina una sesión.

  • • Los mismos errores se repiten en diferentes proyectos
  • • El contexto se pierde al reiniciar el IDE
  • • No hay forma de compartir aprendizajes entre proyectos
  • • Los patrones descubiertos no se documentan automáticamente
🏗️

Arquitectura del Sistema

CMP utiliza una arquitectura de tres capas que separa los agentes de IA, la lógica de negocio, y el almacenamiento persistente.

AI AGENTS LAYERClaude CodeCursorCopilotGeminiCustomHooks & MCPCMP CORE LAYER🧠Memory Manager👥Expert Panel🔍Pattern Detector📋Plan ManagerSQL & VectorCLOUD INFRASTRUCTURETurso (SQLite Edge)Upstash RedisUpstash Vector← Arrows = Data Flow

Capa de Agentes

Donde viven los AI coding assistants

  • Claude Code Hooks - Eventos automáticos
  • MCP Server - Model Context Protocol
  • CLI Commands - Herramientas manuales
  • CLAUDE.md - Configuración del proyecto

CMP Core

La lógica de inteligencia

  • Memory Manager - Gestión de DEV_Items
  • Expert Panel - Revisión multi-experto
  • Pattern Detector - Detección de patrones
  • Plan Manager - Planes con checkpoints

Cloud Infrastructure

Almacenamiento persistente

  • Turso (SQLite) - Base de datos principal
  • Upstash Redis - Cache y sesiones
  • Upstash Vector - Búsqueda semántica
  • Edge Functions - APIs serverless
🔄

Flujo de Datos

Entender cómo fluyen los datos en CMP es clave para aprovechar todo su potencial. Aquí se muestra el ciclo completo desde que un agente inicia sesión hasta que el conocimiento se propaga a otros proyectos.

CMPMemory🚀Session Start⚙️Work & Capture🔍Pattern Detect💾Session End🌐 Knowledge Propagates to SHARED
1

Session Start

Cuando un agente (Claude, Cursor, etc.) inicia sesión, el hook SessionStart se dispara automáticamente.

// .claude/hooks/session-start.sh
#!/bin/bash
npx cmp-standards context load

# Carga:
# - Contexto reciente de DEV_Items
# - Planes activos similares (semantic matching)
# - Patterns aplicables al proyecto
2

Work & Capture

Durante el trabajo, los hooks PreToolUse y PostToolUse capturan decisiones, errores y patrones.

// Hook: PostToolUse (cuando el agente usa una herramienta)
{
  "event": "PostToolUse",
  "tool": "Edit",
  "file": "src/api/auth.ts",
  "captured": {
    "type": "decision",
    "content": "Used bcrypt over argon2 for compatibility",
    "confidence": 0.85
  }
}
3

Pattern Detection

El sistema analiza los items capturados buscando patrones recurrentes.

// Patrón detectado: mismo error 3+ veces
{
  "pattern": "Missing null check on API response",
  "occurrences": 4,
  "files": ["auth.ts", "users.ts", "orders.ts"],
  "suggestion": "Create API response validator",
  "action": "PROPOSE_IMPROVEMENT"
}
4

Session End & Checkpoint

Al terminar, se guarda un checkpoint que permite a otro agente continuar exactamente donde quedaste.

// Checkpoint guardado
{
  "plan_id": "auth-flow-v2",
  "progress": "3/5 tasks completed",
  "next_steps": [
    "Implement refresh token rotation",
    "Add rate limiting"
  ],
  "context": {
    "decisions": [...],
    "blockers": [...]
  }
}
5

Knowledge Propagation

Patrones probados pueden promoverse a SHARED para beneficiar todos los proyectos.

// Promover patrón a SHARED
npx cmp-standards promote PATTERN_123 --to SHARED

// Ahora todos los proyectos ven:
{
  "system": "SHARED",
  "type": "pattern",
  "content": "Always validate API responses with Zod",
  "origin": "MYPROJECT",
  "confidence": 0.95
}
🗄️

Esquema de Base de Datos

CMP utiliza una tabla principal DEV_Items que almacena todos los tipos de conocimiento. Este diseño "single-table" simplifica las queries y permite extensibilidad.

DEV_Itemsid (PK)systemtypesubtypetitlecontentconfidencestatusSYSTEMSPANELCMPSHAREDMYAPPTYPESmemorytaskimprovementpattern

DEV_Items

Tabla principal que almacena todo el conocimiento

ColumnTypeDescription
idTEXTUUID único
systemTEXTCódigo del proyecto (PANEL, CMP, SHARED)
typeTEXTmemory, task, improvement, pattern, decision
subtypeTEXTSubcategoría específica
titleTEXTTítulo corto descriptivo
contentTEXTContenido completo (JSON o texto)
contextTEXTContexto adicional (JSON)
metadataTEXTMetadatos extensibles (JSON)
confidenceREALConfianza 0.0-1.0
statusTEXTactive, resolved, promoted
created_atTEXTTimestamp ISO
updated_atTEXTTimestamp ISO

Por qué Single-Table Design

  • Simplicidad: Una sola query para buscar cualquier tipo de conocimiento
  • Extensibilidad: Nuevos tipos sin cambiar el schema
  • Cross-references: Fácil relacionar items de diferentes tipos
  • Edge-compatible: Funciona perfectamente con Turso (SQLite Edge)
🪝

Sistema de Hooks

Los hooks son el corazón de CMP. Se ejecutan automáticamente en respuesta a eventos del agente, capturando contexto sin intervención manual.

SessionStartLoad contextPreToolUseValidate/Enrich(Tool Executes)PostToolUseCapture resultsStopSave checkpointRepeats per tool

SessionStart

Trigger: Al iniciar Claude Code

Purpose: Cargar contexto previo

  • Cargar DEV_Items recientes
  • Buscar planes similares
  • Inyectar contexto en CLAUDE.md

PreToolUse

Trigger: Antes de usar una herramienta

Purpose: Validar y enriquecer

  • Verificar permisos
  • Añadir contexto relevante
  • Aplicar patterns conocidos

PostToolUse

Trigger: Después de usar una herramienta

Purpose: Capturar resultados

  • Guardar decisiones
  • Detectar errores
  • Actualizar progreso de tareas

Stop

Trigger: Al terminar sesión

Purpose: Persistir estado

  • Guardar checkpoint
  • Sincronizar con cloud
  • Generar resumen de sesión
Ejemplo: Hook PreToolUsetypescript
// .claude/hooks/pre-tool-use.ts
import { CMP } from 'cmp-standards';

export async function preToolUse(event: ToolUseEvent) {
  const { tool, input } = event;

  // Para ediciones de código, buscar patterns relevantes
  if (tool === 'Edit') {
    const patterns = await CMP.patterns.findRelevant({
      file: input.file_path,
      content: input.new_string,
    });

    // Inyectar advertencias si hay anti-patterns
    for (const pattern of patterns) {
      if (pattern.type === 'anti-pattern') {
        return {
          action: 'warn',
          message: `⚠️ ${pattern.title}: ${pattern.suggestion}`
        };
      }
    }
  }

  return { action: 'continue' };
}
👥

Panel de Expertos

El sistema de revisión multi-experto analiza código desde diferentes perspectivas y utiliza votación por consenso para determinar la calidad.

Codeto review🔒🏗️🎨🗄️Parallel ReviewConsensusVoting✅ APPROVEDor ❌ REJECTED+ Findings+ Suggestions
🔒

Security Expert

  • SQL Injection
  • XSS
  • Auth flows
  • Sensitive data exposure

Rechaza: Cualquier vulnerabilidad de seguridad

Performance Expert

  • N+1 queries
  • Bundle size
  • Lazy loading
  • Caching strategies

Rechaza: Issues críticos de rendimiento

🏗️

Architecture Expert

  • SOLID principles
  • Module structure
  • Type safety
  • Dependency injection

Rechaza: Violaciones de tipos o arquitectura

🎨

UX Expert

  • Accessibility
  • Mobile-first
  • Semantic tokens
  • Loading states

Rechaza: Falta de accesibilidad

🗄️

Database Expert

  • Schema validation
  • Migrations
  • Query optimization
  • Indexes

Rechaza: Riesgo de pérdida de datos

🧠

Memory Expert

  • Pattern detection
  • Documentation staleness
  • Repeated code

Rechaza: Nunca (siempre ABSTAIN)

Sistema de Votación

Código CRÍTICO

Auth, pagos, migraciones de DB
Requiere unanimidad (0 REJECT)

Código NORMAL

Features, refactors, UI
Requiere mayoría (3/5 APPROVE)

🧠

Sistema de Memoria

La memoria es el núcleo de CMP. Diferentes tipos de items se almacenan con diferentes propósitos y ciclos de vida.

💭memoryLearnings, decisionsPermanenttaskPlans, todosUntil completed💡improvementSuggestions, rulesPending → Applied🔍patternAnti-patterns, conventionsValidated → Shared
💭

type: "memory"

Conocimiento aprendido durante sesiones

learning

Lecciones aprendidas

decision

Decisiones de diseño

discovery

Descubrimientos sobre el codebase

Lifecycle: Permanente (hasta promoción o eliminación)

type: "task"

Seguimiento de trabajo en progreso

plan

Plan de trabajo con checkpoints

todo

Tarea individual

checkpoint

Estado guardado para handoff

Lifecycle: Activo hasta completar, luego archivado

💡

type: "improvement"

Propuestas de mejora detectadas

suggestion

Idea de mejora

auto-fix

Fix automático propuesto

rule

Regla ESLint generada

Lifecycle: Pendiente → Aplicado/Rechazado

🔍

type: "pattern"

Patrones recurrentes detectados

anti-pattern

Patrón a evitar

best-practice

Patrón recomendado

convention

Convención del proyecto

Lifecycle: Detectado → Validado → Promovido a SHARED

Búsqueda Semántica en Memoriatypescript
import { CMP } from 'cmp-standards';

// Buscar conocimiento relevante
const memories = await CMP.memory.search({
  query: "authentication best practices",
  system: "PANEL",
  types: ["memory", "pattern"],
  limit: 10,
});

// Resultado con scores de similaridad
[
  {
    id: "mem_123",
    title: "JWT vs Session-based auth decision",
    similarity: 0.92,
    content: "Elegimos JWT porque..."
  },
  {
    id: "pat_456",
    title: "Always hash passwords with bcrypt",
    similarity: 0.87,
    content: "Pattern: usar bcrypt..."
  }
]
🔌

Servidor MCP

CMP expone un servidor MCP (Model Context Protocol) que permite a cualquier agente compatible acceder a la memoria y herramientas programáticamente.

Claude Desktopor any MCP client🤖MCP ProtocolCMP MCP ServerTools & ResourcessearchsavepatternsSQL / VectorCloudTursoRedisVector

Tools Expuestos

  • cmp_searchBúsqueda semántica en memoria
  • cmp_saveGuardar nuevo item
  • cmp_patternsListar patrones activos
  • cmp_tasksGestionar tareas y planes
  • cmp_expertsEjecutar revisión de expertos

Resources

  • cmp://contextContexto actual del proyecto
  • cmp://patternsPatrones aplicables
  • cmp://plansPlanes activos
  • cmp://statusEstado del sistema
Configuración MCP en claude_desktop_config.jsonjson
{
  "mcpServers": {
    "cmp": {
      "command": "npx",
      "args": ["cmp-standards", "mcp"],
      "env": {
        "TURSO_DATABASE_URL": "libsql://your-db.turso.io",
        "TURSO_AUTH_TOKEN": "your-token"
      }
    }
  }
}

Esta documentación fue generada y mantenida usando CMP.

Built by agents, for agents