Tu agente de IA comete los mismos errores dos veces. Olvida tus preferencias entre sesiones. No aprende de la repetición.

instinct soluciona esto. Observa patrones de tus sesiones con el agente, rastrea la confianza a lo largo del tiempo y promociona automáticamente los patrones recurrentes a sugerencias que tu agente sigue, sin que tengas que repetirte.

Funciona con cualquier agente compatible con MCP: Claude Code, Cursor, Windsurf, Goose, Codex y otros.

Tabla de contenidos

Cómo funciona

         observe           track            promote           suggest
        ┌───────┐       ┌───────┐        ┌───────┐        ┌───────┐
  You   │Record │  +1   │ Count │  >=5   │Mature │  >=10  │ Rule  │
  work  │pattern├──────>│ hits  ├───────>│suggest├───────>│ auto- │
        └───────┘       └───────┘        └───────┘        │ apply │
                                                          └───────┘

Observar — registra patrones a medida que tu agente trabaja (secuencias de herramientas, preferencias, correcciones recurrentes)
Rastrear — cada reobservación incrementa la confianza
Promocionar — una confianza >= 5 se vuelve mature (sugerido), >= 10 se vuelve rule (aplicado automáticamente)
Sugerir — los patrones maduros guían el comportamiento del agente sin instrucciones explícitas

Características

Auto-promoción — los patrones se promocionan automáticamente a través de niveles de madurez (raw → mature → rule → universal) basados en umbrales de confianza
Detección de cadenas automática — descubre automáticamente patrones secuenciales (seq:A->B) a partir de marcas de tiempo de observación, sin necesidad de definir secuencias manualmente (v1.4.0)
Puntuación de efectividad — rastrea si los patrones sugeridos son confirmados por observaciones posteriores, calcula tasas de confirmación (v1.4.0)
Historial de confianza — línea de tiempo completa de cómo evolucionó la confianza de cada patrón a lo largo del tiempo
Aprendizaje entre proyectos — las reglas observadas en 2 o más proyectos se promocionan automáticamente al nivel universal
Exportación multiplataforma — exporta reglas a formato CLAUDE.md, .cursorrules, .windsurfrules o Codex
Exportación de habilidades del agente — exporta reglas como SKILL.md compatible con agentskills.io
Inyección en CLAUDE.md — inyecta/importa reglas de forma idempotente hacia/desde archivos CLAUDE.md
Detección de duplicados cercanos — encuentra patrones similares y fusiónalos mediante alias
Alias de patrones — redirige observaciones de variantes ortográficas a patrones canónicos
Búsqueda de texto completo — búsqueda potenciada por FTS5 a través de patrones, metadatos y explicaciones
Recolección de basura — degrada patrones obsoletos, fusiona duplicados, limpia huérfanos, reconstruye índices
Copia de seguridad y restauración — copia de seguridad y restauración a nivel de SQLite con comprobaciones de estado

Instalación

pip install instinct-mcp

Primeros pasos en 60s

Si aún no lo has instalado, ejecuta pip install instinct-mcp.
Añade instinct a tu cliente MCP.
Claude Code (una línea):
```
claude mcp add instinct -- instinct serve
```
Cursor / Windsurf / Goose / otros clientes MCP — añádelo a la configuración MCP de tu cliente:
```
{
  "mcpServers": {
    "instinct": {
      "command": "instinct",
      "args": ["serve"]
    }
  }
}
```
Registra un patrón y solicita sugerencias:

instinct observe "seq:test->fix->test"
instinct suggest

Si suggest devuelve una lista vacía, sigue observando patrones recurrentes. Las sugerencias aparecen una vez que la confianza alcanza el nivel mature.

Verificación rápida

instinct observe "seq:test->fix->test"
instinct suggest

Salud del repositorio

CI y CodeQL se ejecutan en push y pull request
Dependabot rastrea actualizaciones semanales (GitHub Actions + pip)
La rama predeterminada protegida (master) requiere revisión y conversaciones resueltas

Inicio rápido

1. Añádelo a tu agente

Claude Code — añádelo a .mcp.json en la raíz de tu proyecto:

{
  "mcpServers": {
    "instinct": {
      "command": "instinct",
      "args": ["serve"]
    }
  }
}

Codex CLI — añádelo a ~/.codex/config.toml:

[mcp_servers.instinct]
command = "instinct"
args = ["serve"]

Cursor / Windsurf — añádelo a tu configuración MCP:

{
  "mcpServers": {
    "instinct": {
      "command": "instinct",
      "args": ["serve", "--transport", "sse"]
    }
  }
}

2. Observa cómo aprende

A medida que trabajas, tu agente comienza a notar patrones:

Session 1:  observe("seq:test->fix->test")          → confidence 1 (raw)
Session 3:  observe("seq:test->fix->test")          → confidence 3 (raw)
Session 5:  observe("seq:test->fix->test")          → confidence 5 (mature ✓)
            suggest() → "When tests fail, apply fix and re-run tests"

Después de suficientes repeticiones, instinct comienza a sugerir el patrón de vuelta: tu agente se adapta a cómo trabajas tú.

Cómo son los patrones

# Tool sequences your agent repeats
instinct observe "seq:lint->fix->lint"
instinct observe "seq:build->test->deploy"

# Your preferences it should remember
instinct observe "pref:style=black" --cat preference
instinct observe "pref:commits=conventional" --cat preference

# Fixes it keeps rediscovering
instinct observe "fix:missing-import" --cat fix_pattern
instinct observe "fix:utf8-encoding-windows" --cat fix_pattern

# Tools that work better together
instinct observe "combo:pytest+coverage" --cat combo

Convención de nombres

Prefijo	Uso para	Ejemplo
`seq:`	Secuencias de acción	`seq:lint->fix->lint`
`pref:`	Preferencias de usuario	`pref:style=black`
`fix:`	Correcciones recurrentes	`fix:missing-import`
`combo:`	Combinaciones de herramientas	`combo:pytest+coverage`

Niveles de madurez

Nivel	Confianza	Comportamiento
raw	< 5	Observado, almacenado, aún no accionable
mature	>= 5	Devuelto por `suggest()` — el agente lo usa como guía
rule	>= 10	Exportado por `export_rules()` — lo suficientemente fuerte para aplicar automáticamente
universal	rule + 2 proyectos	Regla entre proyectos, sugerida en todas partes

Herramientas MCP

Herramienta	Qué hace
`observe`	Registra un patrón (auto-incrementa la confianza al repetir)
`suggest`	Obtiene patrones maduros para guiar el comportamiento actual
`list_instincts`	Explora todos los patrones observados con filtros
`get_instinct`	Busca un patrón específico
`consolidate`	Promociona patrones que cruzaron umbrales de confianza + detecta cadenas
`search_instincts`	Búsqueda de texto completo a través de patrones y metadatos
`stats`	Estadísticas resumidas del almacén de instinct
`export_rules`	Exporta patrones de nivel de regla como datos estructurados
`alias_pattern`	Crea un alias para fusionar patrones duplicados
`import_patterns`	Importación masiva de patrones desde una lista de diccionarios
`session_summary`	Instantánea de fin de sesión con consolidación automática
`trending`	Muestra los patrones de crecimiento más rápido en el período reciente
`export_claude_md`	Exporta reglas formateadas para CLAUDE.md
`export_skill`	Exporta reglas como Habilidad de Agente (SKILL.md / agentskills.io)
`inject_claude_md`	Inyecta reglas en un archivo CLAUDE.md (idempotente)
`find_duplicates`	Encuentra patrones casi duplicados para fusionar
`import_claude_md`	Importa patrones desde un archivo CLAUDE.md
`history`	Historial de confianza para un patrón a lo largo del tiempo
`export_platform`	Exporta reglas para Cursor, Windsurf, Codex, etc.
`gc`	Recolección de basura: degradación + deduplicación + limpieza de huérfanos + reconstrucción FTS
`detect_chains`	Detecta automáticamente cadenas de patrones secuenciales a partir de marcas de tiempo
`effectiveness`	Muestra puntuaciones de efectividad de sugerencias (tasas de confirmación)

Prompts MCP

Prompt	Qué hace
`instinct_rules`	Obtiene todas las reglas de instinct como instrucciones para el agente
`instinct_suggestions`	Obtiene sugerencias de patrones maduros para el proyecto actual

Referencia de CLI

# Core
instinct observe <pattern>       # Record/reinforce a pattern
instinct get <pattern>           # Look up a specific pattern
instinct list                    # List all instincts
instinct suggest                 # Get mature suggestions
instinct consolidate             # Auto-promote + detect chains
instinct stats                   # Summary statistics
instinct delete <pattern>        # Remove a pattern

# Analysis
instinct trending                # Fastest-growing patterns
instinct history <pattern>       # Confidence history over time
instinct effectiveness           # Suggestion confirmation rates
instinct detect-chains           # Auto-detect sequential chains

# Export
instinct export-rules            # Export rules as JSON
instinct export-claude-md        # Export rules as CLAUDE.md markdown
instinct export-skill            # Export rules as Agent Skill (SKILL.md)
instinct export-platform <fmt>   # Export for cursor/windsurf/codex
instinct export-all              # Export all instincts as JSON

# Import & Sync
instinct inject <path>           # Inject rules into CLAUDE.md (idempotent)
instinct import-claude-md <path> # Import patterns from CLAUDE.md
instinct import <file.json>      # Bulk import from JSON

# Maintenance
instinct gc                      # Garbage collection (decay + dedup + cleanup)
instinct decay                   # Reduce stale patterns
instinct dedup                   # Find/merge near-duplicate patterns
instinct alias <pat> <target>    # Create a pattern alias
instinct aliases                 # List all aliases

# Infrastructure
instinct serve                   # Start MCP server
instinct fingerprint             # Print project fingerprint for cwd
instinct backup                  # Create database backup
instinct restore <file>          # Restore from backup
instinct doctor                  # Run health checks

Todos los comandos admiten --json para salida estructurada.

Opciones de Observe

instinct observe "seq:a->b" \
  --cat sequence              # Category: sequence|preference|fix_pattern|combo
  --source claude-code        # Which agent/tool recorded this
  --project auto              # Project fingerprint (auto-detected from cwd)
  --explain "why this matters"

Opciones de servidor

instinct serve                              # stdio (default, for Claude Code)
instinct serve --transport sse              # SSE for remote/HTTP clients
instinct serve --transport streamable-http  # Streamable HTTP
instinct serve --port 3777                  # Custom port (default: 3777)

Biblioteca de Python

from instinct.store import InstinctStore

store = InstinctStore()  # uses ~/.instinct/instinct.db

# Record patterns
store.observe("seq:test->fix->test", source="my-tool")
store.observe("seq:test->fix->test")  # confidence = 2

# Query
suggestions = store.suggest()                     # mature+ patterns
results     = store.search("test")                # full-text search
rules       = store.export_rules()                # rule-level only

# Lifecycle
store.consolidate()                               # promote + detect chains
store.decay(days_inactive=90)                     # fade stale patterns

# Auto-chain detection
chains = store.detect_chains(window_minutes=5, min_occurrences=3)

# Effectiveness scoring
eff = store.effectiveness(days=30)

# Stats
print(store.stats())
# {'total': 42, 'raw': 30, 'mature': 10, 'rules': 2, 'avg_confidence': 4.2, ...}

Ruta de base de datos personalizada

store = InstinctStore(db_path="/path/to/custom.db")

Aprendizaje entre proyectos

instinct aplica hash a tu directorio de trabajo en una huella digital del proyecto. Esto significa:

Patrones específicos del proyecto solo se sugieren cuando estás en ese proyecto
Patrones globales (campo de proyecto vacío) se sugieren en todas partes
Reglas universales — los patrones que alcanzan el nivel rule en 2 o más proyectos se promocionan automáticamente a universal, sugeridos en todos los proyectos

# See your current project's fingerprint
instinct fingerprint
# → a1b2c3d4e5f6

Almacenamiento

Base de datos: SQLite (modo WAL) en ~/.instinct/instinct.db
Dependencias: Solo mcp>=1.0.0
Python: >= 3.11
Configuración: ~/.instinct/config.toml opcional para sobrescribir umbrales

Comparativa

	instinct	CLAUDE.md manual	.cursorrules
Aprende automáticamente	Sí	No	No
Memoria entre sesiones	Sí	Sí	Sí
Puntuación de confianza	Sí	No	No
Detección de cadenas automática	Sí	No	No
Seguimiento de efectividad	Sí	No	No
Degradación de patrones obsoletos	Sí	No	No
Aprendizaje entre proyectos	Sí	No	No
Funciona entre agentes	Sí (MCP)	Solo Claude	Solo Cursor
Exportación multiplataforma	Sí	N/A	N/A
Requiere edición manual	No	Sí	Sí

Licencia

MIT

instinct