piia-engram

Piia Engram

Identidad de trabajo de IA local-primero que puedes ver, editar y anular — portable entre tus herramientas de codificación MCP.

Dile a la IA una vez quién eres, cómo trabajas y qué significa "bueno". Claude Code, Codex, Cursor, Windsurf y otras herramientas compatibles con MCP pueden partir de la misma capa de identidad de trabajo de IA — archivos locales que tú posees, sin cuenta en la nube, sin memoria oculta que no puedas inspeccionar.

Instalar · Verlo en acción · Herramientas compatibles · Herramientas MCP · Preguntas frecuentes

ENGLISH | 中文

Listado en:

También listado en: awesome-agents · Awesome-MCP-ZH · mcpservers.org · Cursor Directory · ModelScope · PulseMCP

Resumen: piia-engram es una capa de identidad de IA personal local-primero. Ayuda a múltiples agentes de codificación a partir del mismo entendimiento de ti: tus preferencias, estándar de calidad, lecciones aprendidas, decisiones y contexto de proyecto. No es una base de datos de memoria de agentes; es la capa propiedad del usuario por encima de tus herramientas.

¿Por qué no usar simplemente la memoria nativa? Claude Code, Codex, Cursor y Windsurf están añadiendo sus propias memorias y reglas. Son útiles, pero están limitadas a una herramienta o espacio de trabajo. piia-engram te da una capa de identidad portable por encima de ellas: archivos locales que posees, conocimiento propuesto por IA que revisas, y contexto que puede seguirte entre herramientas.

Modelo de confianza en cuatro líneas:

• Sin cuenta en la nube: instala con pip, mantén el almacén principal en tu máquina.
• Archivos locales: la identidad y el conocimiento viven bajo ~/.engram/ como JSON/Markdown.
• Aprobación del usuario: la IA escribe localmente; los elementos de alto riesgo (credenciales, comandos de shell, configuración MCP, reglas de permisos) esperan tu revisión, mientras que las escrituras de riesgo bajo/medio se absorben automáticamente pero son totalmente auditables y reversibles. Configura ENGRAM_APPROVAL=strict para controlar cada escritura.
• Límites documentados: consulta Modelo de confianza, Privacidad y Seguridad.

¿Quieres pruebas? Consulta la prueba de continuidad entre herramientas en vivo — una memoria escrita por Claude Code, leída por Codex a través de un único almacén local — o la demo de código reproducible con un solo comando.

Verlo en acción

You  → "Help me refactor this auth module"

# WITHOUT piia-engram: AI starts from scratch
AI   → "What language? What framework? What's your testing preference?"

# WITH piia-engram: AI can load your approved context
AI   → "Based on your preference for pytest + 90% coverage, and your
        lesson about always separating auth middleware from business
        logic (from the March incident), here's my approach..."

Y nunca tienes que aceptarlo por fe — Memory Lens (engram preview --html) muestra exactamente lo que cualquier llamador de IA recibiría, y qué retuvo la gobernanza, antes de enviar nada:

Arriba: un informe real de un almacén de demostración — 4 elementos expuestos; una nota de preparación no revisada y una lección que contiene una credencial son retenidas, con el secreto mostrado como [REDACTED].

Instalar

pip install piia-engram && engram setup

El asistente detecta automáticamente tus herramientas de IA — Claude Code, Cursor, Codex, Claude Desktop — lista los archivos de configuración exactos que tocará, y escribe la conexión MCP tras una confirmación de una sola tecla (cada escritura se respalda primero; si rechazas, nada cambia). Previsualiza tu tarjeta de identidad, luego reinicias tu herramienta configurada; la primera conversación puede cargar tu contexto aprobado mediante herramientas de inicio o búsqueda. (recorrido completo ↓)

Herramientas compatibles

Los niveles de evidencia siguen el runbook de validación de clientes de agentes: L0 = no probado, L1 = instalado, L2 = lectura/búsqueda observada, L3 = puente de archivos estáticos, L4 = continuidad entre clientes.

En números

Estos son hechos actuales del repositorio de docs/public-facts.json. Los registros públicos y las insignias de paquetes se actualizan solo durante el lanzamiento/publicación.

Tu IA te olvida cada vez que cambias de herramienta o inicias un nuevo chat. piia-engram arregla la transición.

Cada vez que abres una nueva ventana de chat, cambias de Claude Code a Codex, actualizas tu herramienta de IA, o te mueves a un proyecto diferente, vuelves a cero:

• tus preferencias de comunicación — desaparecidas
• tus estándares de código y nivel de calidad — olvidados
• los errores de los que ya aprendiste — perdidos
• por qué tomaste esa decisión de arquitectura el mes pasado — borrado

Esto sucede porque la memoria de IA hoy está encerrada dentro de cada plataforma. Pertenece a la herramienta, no a ti. La herramienta se actualiza, se reinicia o se reemplaza — y tu contexto desaparece con ella.

piia-engram te da una capa de identidad personal que vive en tu máquina, independiente de cualquier herramienta de IA. Se lo dices una vez quién eres, cómo trabajas y qué has aprendido. Las herramientas compatibles con MCP pueden leer el mismo contexto aprobado. Nuevo chat, nueva herramienta, nueva versión — tu identidad sigue siendo portable.

piia-engram no es una base de datos de memoria de agentes. Herramientas como Mem0, Zep y Letta almacenan contexto de tareas e historial de sesiones para agentes de IA. piia-engram almacena quién eres como persona — tu identidad, preferencias, lecciones ganadas con esfuerzo y decisiones clave. Es una capa diferente: no lo que sucedió en una tarea, sino quién está detrás de cada tarea.

¿Por qué piia-engram?

Quién usa piia-engram

piia-engram está construido para desarrolladores que usan múltiples herramientas de codificación de IA y están cansados de reexplicarse.

Si cambias entre Claude Code, Codex y Cursor — tus estándares de código, decisiones de arquitectura y lecciones ganadas con esfuerzo se reinician cada vez. piia-engram hace que cada herramienta parta del mismo entendimiento de quién eres.

Si abres 10+ ventanas de chat de IA a la semana — cada una empieza desde cero. piia-engram permite que cada conversación parta del mismo contexto de identidad y conocimiento aprobado.

Si has perdido preferencias después de una actualización de herramienta — tu identidad vive en tu máquina, no dentro de ninguna plataforma. Las actualizaciones, reinicios y migraciones no tocan tu memoria.

Qué almacena piia-engram

Todos los datos viven bajo ~/.engram/ como archivos JSON y Markdown en texto plano que puedes abrir, editar, respaldar o migrar tú mismo.

• Identidad: quién eres, cómo te comunicas, qué idiomas prefieres
• Estándares de calidad: tu nivel de revisión de código, expectativas de cobertura de pruebas, qué te niegas a publicar
• Preferencias: estilo de codificación, comportamiento de IA, cómo te gustan las explicaciones
• Límites de confianza: qué campos mantener privados, qué herramientas pueden acceder
• Instantáneas de proyecto: contexto para trabajo en curso, capturado y recargable
• Lecciones aprendidas: errores, sorpresas, cosas que funcionaron y no
• Decisiones clave: qué elegiste, qué descartaste y por qué
• Conocimiento de dominio: ideas reutilizables entre proyectos y herramientas

Qué hace piia-engram (Más allá del almacenamiento)

La mayoría de las herramientas de memoria son pasivas — pones cosas dentro, te las devuelven. piia-engram también es activa.

Herencia de conocimiento entre proyectos
Describe un nuevo proyecto en texto plano. get_knowledge_inheritance devuelve un paquete inicial curado de las lecciones y decisiones más relevantes de todo en lo que has trabajado. Tu décimo proyecto se beneficia de los nueve anteriores — a una sola llamada de herramienta.

Captura pasiva de conocimiento
Pega un resumen de sesión en extract_session_insights y piia-engram extrae y almacena las lecciones y decisiones. Sin toma de notas manual. El conocimiento se acumula a través de conversaciones normales de IA.

Funciona con herramientas que no soportan MCP
ChatGPT, Gemini, Kimi — get_identity_card exporta una tarjeta de identidad Markdown lista para pegar. Tu contexto viaja incluso a herramientas que no pueden conectarse directamente. Extracción automática de playbooks
Completa un flujo de trabajo de varios pasos — publicar en PyPI, desplegar en Cloudflare, publicar en el Registro MCP — y piia-engram lo detecta al final de la sesión. Genera un borrador estructurado de playbook (pasos, dificultades, palabras clave de activación) y lo guarda en un área de preparación. La próxima vez que hagas la misma tarea, la IA puede recuperar el playbook confirmado como referencia pasiva, recorrer los pasos contigo y registrar el resultado. No se requiere registro manual — Engram inicia el borrador, tú lo confirmas, y la IA anfitriona mantiene la responsabilidad. Consulta Extracción automática de playbooks a continuación.

Registro local de herramientas
Las herramientas de IA buscan constantemente programas locales, tiempos de ejecución y CLIs. register_tool registra qué está instalado y dónde; find_tool lo recupera al instante. Se acabó el which python en cada sesión — el mapa del entorno persiste entre herramientas y conversaciones.

Salud del conocimiento y descubrimiento
get_knowledge_overview saca a la luz lecciones obsoletas (no revisadas en más de 30 días), calcula una puntuación de salud de 0 a 100 en cuatro dimensiones (actualidad, calidad, cobertura, limpieza) y señala vacíos que vale la pena revisitar. explore_knowledge escanea tu base de conocimiento en busca de casi duplicados (y recorre elementos relacionados/similares) con comandos de fusión accionables. manage_relation conecta lecciones y decisiones relacionadas en un grafo de conocimiento navegable.

Búsqueda híbrida (opcional, desactivada por defecto)
La búsqueda por palabras clave predeterminada permanece sin cambios. Activa la recuperación híbrida — texto completo FTS5 más una capa semántica de vectores — para recuperación multilingüe, p. ej., una consulta en inglés que encuentra una nota en chino: pip install "piia-engram[vector]" y establece ENGRAM_SEARCH=hybrid, o deja que engram setup la active con una sola pulsación de tecla. El índice es un archivo SQLite reconstruible; tu almacén JSON sigue siendo la única fuente de verdad. Consulta docs/hybrid-search.md.

Inicio rápido

pip install piia-engram
engram setup

¿Nuevo en piia-engram? Consulta el inicio rápido de primer valor más completo para la ruta instalar -> primer recuerdo -> recuperación en sesión nueva usando solo las 19 herramientas principales predeterminadas, o la Guía de usuario completa que cubre instalar -> primer valor -> continuidad entre herramientas -> gobernanza -> privacidad -> preguntas frecuentes. Hay tarjetas de configuración específicas para cada anfitrión disponibles para Claude Code, Codex y Cursor. Para borradores de contexto seguro solo de propuesta, reproducción, actualidad/conflicto y evidencia, consulta Gobernanza de contexto.

El asistente de configuración:

1. Detectará tu entorno de Python
2. Te permitirá elegir la carpeta de datos de Engram (~/.engram, otra unidad o una ruta personalizada)
3. Detectarás tus herramientas de IA, listará los archivos de configuración exactos que tocará y escribirá la conexión MCP tras una confirmación de una sola tecla (con copia de seguridad previa; si rechazas, no se tocan)
4. Te guiará a través del conocimiento semilla (rol, pila tecnológica, idioma)
5. Importará inteligentemente reglas de tus archivos CLAUDE.md / .cursorrules existentes
6. En modo avanzado (engram setup --advanced), mostrará tus preferencias de privacidad opcionales (sincronización entre herramientas, estadísticas anónimas)
7. Vista previa de tu tarjeta de identidad de IA — prueba inmediata de valor

Después de que la configuración escriba la conexión MCP (confirmas primero en el aviso), reinicia tu herramienta de IA. Muchos clientes pueden llamar a get_user_context al inicio; cuando un anfitrión no lo hace de forma proactiva, una llamada explícita a search_knowledge o get_resume_brief sigue siendo la ruta L2 esperada.

Para ejecuciones no interactivas o de CI, omite el aviso de confirmación y escribe directamente:

engram setup --apply-external-config

En cualquier caso, cada escritura de configuración externa se respalda en la carpeta de datos de Engram seleccionada, y rechazar el aviso deja intacta toda configuración externa.

Comprueba la salud en cualquier momento:

engram status        # redacted install + memory health summary
engram status --html # write a local redacted status page
engram preview --as automation  # see exactly what a given AI caller would receive (read-only)
engram continuity    # metadata-only proof that cross-tool handoff is ready
engram management    # metadata-only review/playbook management view
engram doctor        # diagnose all tools
engram doctor --fix  # auto-repair issues + inject missing instructions
engram repair-encoding        # dry-run scan for garbled / mojibake text
engram repair-encoding --apply  # repair reversible cases with a backup

engram continuity es solo de metadatos: informa recuentos de sesiones guardadas, herramientas contribuyentes, preparación del resumen de reanudación y señales agregadas de carga de contexto / cierre sin imprimir cuerpos de memoria, eventos de telemetría sin procesar, ID de sesión o rutas locales.

Para una prueba de bucle sintético legible por máquina, ejecuta:

python demos/cross_tool_continuity_demo.py --json

engram continuity informa metadatos de preparación. El JSON de demostración prueba un bucle aislado de escribir -> reanudar -> buscar -> procedencia usando solo datos sintéticos.

Para evidencia de lanzamiento más amplia, ejecuta el benchmark sintético MCIC:

python demos/mcic_benchmark.py --json

MCIC v1 contiene 10 escenarios de continuidad con etiquetas de propósito que cubren recuperación explícita, señales implícitas de personalización, señales de protección contra premisas falsas, límites de acciones públicas, selección de HEAD en cadenas de versiones, control negativo y procedencia. Su afirmación es limitada: Engram pone la señal correcta a disposición del siguiente cliente; el cumplimiento del modelo en vivo aún requiere pruebas A/B separadas.

Confianza y evidencia

piia-engram trata las afirmaciones de confianza como artefactos de lanzamiento, no como texto de marketing:

Verifícalo tú mismo (5 minutos)

No te fíes de la tabla anterior — ejecuta las comprobaciones en tu propia máquina:

1. Comprueba tu configuración — engram doctor informa herramientas detectadas, salud del almacén y el modo de capacidad activo.
2. Mira lo que ve la IA — engram preview --as automation renderiza el contexto exacto que recibiría un llamador (solo lectura, no se envía nada).
3. Controla la superficie — establece ENGRAM_TOOLS=core (o compón grupos) y vuelve a ejecutar engram doctor para confirmar que informa la superficie principal esperada. Consulta modos de capacidad.
4. Audita tus datos — sigue el runbook de auditoría de soberanía de datos para confirmar que los datos de identidad y conocimiento permanecen bajo tu raíz de Engram, con escrituras externas explícitas y auditadas.
5. Comprueba las afirmaciones — cada afirmación de confianza en evidencia de confianza se asigna a una comprobación determinista o ruta de inspección que puedes ejecutar localmente.

Configura para tu herramienta de IA

# Guided setup; confirms before writing external client configs (backed up first)
engram setup
# Skip the confirmation prompt for non-interactive/CI runs
engram setup --apply-external-config
# Or manual:
claude mcp add piia-engram -- piia-engram-mcp

{
  "mcpServers": {
    "piia-engram": {
      "command": "piia-engram-mcp",
      "args": ["--transport", "stdio"]
    }
  }
}

{
  "command": "python",
  "args": ["-m", "piia_engram.mcp_server"]
}

{
  "mcpServers": {
    "piia-engram": {
      "command": "python",
      "args": ["-m", "piia_engram.mcp_server"]
    }
  }
}

{
  "mcpServers": {
    "piia-engram": {
      "command": "python",
      "args": ["-m", "piia_engram.mcp_server"]
    }
  }
}

{
  "mcpServers": {
    "piia-engram": {
      "command": "python",
      "args": ["-m", "piia_engram.mcp_server"]
    }
  }
}

{
  "mcpServers": {
    "piia-engram": {
      "command": "python",
      "args": ["-m", "piia_engram.mcp_server"]
    }
  }
}

Verifica tu configuración

Después de la configuración, ejecuta engram doctor para verificar que todo esté conectado:

$ engram doctor

  Detected 3 AI tool(s):
    [ok] Claude Code — Engram configured
    [ok] Cursor — Engram configured
    [ok] Codex — Engram configured

  [ok] All configured tools look healthy.

  ── Functional Checks ──
    [ok] piia_engram.core importable
    [ok] Engram initialized (~/.engram)
    [ok] Identity loaded (role: Senior Backend Developer)
    [ok] quick_context.md ready (4096 bytes)
    [ok] MCP server: 18 tools registered

  -- Terminal encoding --

    [ok] stdout/stderr: utf-8 / utf-8
    [ok] PYTHONIOENCODING not set (stdout/stderr already UTF-8)
    [ok] Runtime encodings: preferred=UTF-8, filesystem=utf-8

  -- Config Integrity --

    [ok] MCP configs: 3/13 files found, 3 configured
    [ok] Instruction files: 3/4 found, 3 fresh
    [ok] Project rule files: 1 found
    [ok] Shared instructions: 1 found
    [ok] Claude hooks: 4/4 registered
    [ok] Report is metadata-only (hashes + counts; no rule bodies)

  -- Continuity --

    [--] No saved agent sessions yet
         Run an AI session, then wrap up or stop the tool to create one.
    [ok] Resume brief builds (2 section(s))

Para comprobaciones de compatibilidad legibles por máquina, ejecuta engram capabilities --json. Informa códigos de capacidad estables y versiones de contrato sin leer memoria de usuario o contenido de proyecto; MCP doctor(output_format="json") incluye la misma huella.

Actualización

pip install --upgrade piia-engram

Después de actualizar, piia-engram migra automáticamente cualquier configuración MCP obsoleta la próxima vez que su servidor se inicie (modo stdio). Si tu herramienta de IA aún muestra un error de "MCP desconectado" después de reiniciar, ejecuta:

piia-engram doctor        # show what's wrong
piia-engram doctor --fix  # auto-repair and fix in one step

Luego reinicia la herramienta de IA afectada. El comando doctor comprueba las ubicaciones de configuración MCP de Claude Code, Cursor, Codex, Windsurf, Claude Desktop y las compatibles con la comunidad, elimina entradas de servidor obsoletas e imprime un resumen de integridad de configuración solo de metadatos.

Despliegue remoto

Ejecuta piia-engram en tu propio servidor y conéctate desde cualquier lugar.

Configuración del servidor

# Install with remote support
pip install piia-engram[remote]

# Generate an auth token
python -c "import secrets; print(secrets.token_urlsafe(32))"
# Save the output, e.g. "abc123..."

# Start in SSE mode
ENGRAM_AUTH_TOKEN=abc123... python -m piia_engram.mcp_server --transport sse --host 0.0.0.0 --port 8767

Configuración del cliente (Claude Code)

{
  "mcpServers": {
    "piia-engram": {
      "url": "http://your-server:8767/sse",
      "headers": {
        "Authorization": "Bearer abc123..."
      }
    }
  }
}

Configuración del cliente (Cursor)

{
  "mcpServers": {
    "piia-engram": {
      "url": "http://your-server:8767/sse",
      "headers": {
        "Authorization": "Bearer abc123..."
      }
    }
  }
}

Notas de seguridad:

• Usa siempre HTTPS en producción, detrás de nginx o caddy con TLS.
• El token de autenticación protege tus datos de identidad. Mantenlo en secreto.
• El enlace predeterminado es 127.0.0.1 solo para localhost. Usa 0.0.0.0 solo detrás de un proxy inverso.
• Establece ENGRAM_CORS_ORIGINS para restringir el acceso entre orígenes (p. ej., https://your-domain.com).
• Los datos permanecen en tu servidor y nunca tocan nubes de terceros.

Herramientas MCP

piia-engram incluye 59 herramientas MCP. Por defecto, solo se cargan las 19 herramientas Tier-1 Core para mantener limpio el contexto de la IA. "Core" significa "usadas en la mayoría de las sesiones", no "solo lectura": algunas herramientas principales escriben memoria local o archivos de exportación restringidos al propietario, y la capa de gobernanza sigue controlando esos efectos secundarios. Para la vista breve del operador, consulta la chuleta MCP. Para desbloquear las 59 herramientas, añade ENGRAM_TOOLS=all a tu configuración MCP:

También puedes exponer modos de capacidad componibles como gestión del conocimiento, gobernanza, administración o integraciones; consulta la guía de modos de capacidad.

{
  "mcpServers": {
    "piia-engram": {
      "command": "python",
      "args": ["-m", "piia_engram.mcp_server"],
      "env": { "ENGRAM_TOOLS": "all" }
    }
  }
}

Sincronización de inicio: Engram reconcilia recuerdos/fragmentos de configuración de herramientas de IA locales cuando un servidor MCP se inicia. Por defecto, esto se ejecuta en segundo plano para que los clientes stdio puedan inicializarse rápidamente. Establece ENGRAM_MCP_STARTUP_SYNC=eager para restaurar la sincronización de inicio síncrona, o ENGRAM_MCP_STARTUP_SYNC=off para omitir la sincronización de inicio en brazos de prueba sensibles a la latencia. ENGRAM_EPHEMERAL=1 también omite la sincronización de inicio y el trabajo de migración en clientes de contenedor/efímeros.

Tier-1 Core (18 herramientas — flujo de trabajo diario)

Nivel 2 — Avanzado (40 herramientas — gestión del conocimiento, revisión, gobernanza, importación/exportación)

Las herramientas avanzadas incluyen integraciones locales opcionales, superficies de propietario/administrador y utilidades de mantenimiento. Las herramientas que exportan archivos, importan almacenes completos, generan páginas de revisión o mutan la confianza del llamador son superficies de propietario/administrador/exportación incluso cuando son capacidades de producto ampliamente útiles. Las operaciones relacionadas se consolidan en herramientas únicas con un selector mode/action (v4.0).

La migración del ámbito del Playbook heredado (clasificar / aplicar / revertir / cola de revisión) se movió fuera de la superficie MCP hacia la CLI local solo para propietario: engram playbook scope classify|apply|rollback|queue|resolve (vista previa por defecto; las escrituras requieren --apply --yes).

Extracción automática de playbooks

piia-engram puede detectar flujos de trabajo de varios pasos que completes durante una sesión y redactar automáticamente playbooks estructurados — sin necesidad de registro manual.

Cómo funciona

1. Detección — Cuando llames a wrap_up_session o save_agent_context, piia-engram escanea señales de flujo de trabajo procedimental: pasos de punto de control, verbos de acción y palabras clave de activación.
2. Generación de borrador — Si se detecta un flujo de trabajo, se crea un borrador de playbook con pasos, dificultades, palabras clave de activación y condiciones previas. La información sensible (claves API, tokens, rutas absolutas) se redacta automáticamente antes del almacenamiento.
3. Etapa de preparación — El borrador se guarda en un área de preparación, nunca se promueve automáticamente a verificado. Tú lo revisas y confirmas antes de que se convierta en un playbook de confianza.
4. Contrato de esquema — Los playbooks almacenados se normalizan en un contrato versionado: palabras clave de activación, condiciones previas, dificultades, pasos estructurados y declaraciones opcionales de required_tools. Los borradores ligeros siguen siendo revisables, pero llevan advertencias de calidad legibles por máquina.
5. Resolución de herramientas — Los playbooks declaran necesidades de herramientas por nombre o propósito, mientras que las rutas locales permanecen en el registro de herramientas. playbook_execution (acción prepare) devuelve resolved_tools, tools_ready y missing_tools en tiempo de ejecución para que la IA anfitriona pueda ver qué herramientas locales están disponibles sin almacenar rutas resueltas en el playbook.
6. Reutilización y resultado — La próxima vez que una herramienta de IA encuentre una tarea similar, search_knowledge coincide con las palabras clave de activación y devuelve el playbook como referencia pasiva. La IA anfitriona recorre los pasos contigo y playbook_execution (acción status) informa un resumen de resultados (pending, partial, succeeded o failed) en lugar de tratar los pasos omitidos como éxito silencioso.

Filosofía de diseño: Engram inicia, tú confirmas, la IA aplica

La extracción automática de playbooks no es completamente automática. piia-engram detecta el flujo de trabajo y genera un borrador aproximado — pero el borrador permanece en preparación hasta que lo confirmes explícitamente. Una vez confirmado, las herramientas de IA pueden usar el playbook como referencia pasiva gobernada y registrar los resultados de los pasos; Engram no ejecuta silenciosamente el flujo de trabajo por ellas. Esto mantiene a los humanos en el circuito para el control de calidad mientras elimina el trabajo manual de escribir procedimientos operativos.

Niveles de confianza

Redacción de información sensible

Antes de almacenar cualquier borrador, piia-engram redacta automáticamente:

• Claves API y tokens (Bearer, sk-, ghp_, etc.)
• Rutas de archivo absolutas (Windows y Unix)
• Direcciones de correo electrónico
• Secretos de variables de entorno

Interruptor de apagado

Los usuarios pueden desactivar o reactivar la extracción automática de playbooks en cualquier momento:

• Desactivar: Dile a tu IA "关闭 playbook" / "stop playbook" / "disable playbook auto-extraction"
• Activar: Dile a tu IA "开启 playbook" / "start playbook" / "enable playbook auto-extraction"

La IA llama a update_identity(field="preferences", ...) para alternar playbook_auto_extract. El valor predeterminado es activado.

Creación manual de playbooks

Siempre puedes crear playbooks manualmente con add_playbook, independientemente de la configuración de extracción automática. El interruptor de apagado solo afecta la detección automática durante wrap_up_session.

Diseño de datos

~/.engram/
|-- schema_version.json
|-- identity/
|   |-- profile.json
|   |-- preferences.json
|   |-- quality_standards.json
|   `-- trust_boundaries.json
|-- knowledge/
|   |-- lessons.json
|   |-- decisions.json
|   `-- domains.json
|-- playbooks/
|   |-- _index.json
|   `-- {playbook_id}.json
|-- tools/
|   `-- registry.json
|-- projects/
|   `-- {project_id}.json
|-- contexts/
|   `-- {tool_name}/
|       `-- {session_id}.md
|-- exports/
`-- compat/
    `-- openclaw/

Posee y exporta tus datos

Todo vive en JSON local que posees — inspecciónalo, edítalo, haz copias de seguridad o elimínalo directamente. Tres rutas de exportación explícitas, cada una con un límite diferente:

Las exportaciones están restringidas al propietario cuando ENGRAM_GOVERNANCE=1 (consulta docs/governance.md). No hay copia en la nube ni memoria oculta: lo que exportas es exactamente lo que está en tu disco.

Soberanía de datos local. La copia de seguridad y la restauración cubren solo el directorio de Engram — engram backup-plan imprime una lista solo de metadatos de qué copiar antes de una actualización (no lee cuerpos de conocimiento almacenados y nunca sale de la raíz de Engram). Para copias de seguridad JSON, import_engram(..., dry_run=True) o engram import <backup.json> devuelve un plan de fusión solo de metadatos con recuentos de agregar/omitir/conflicto antes de cualquier escritura; --apply --yes es necesario para mutar el almacén local. Las lecciones con el mismo resumen y las decisiones con la misma pregunta con campos semánticos divergentes se previsualizan como candidatos de cadena de versiones; se materializan solo cuando el propietario ejecuta explícitamente engram import <backup.json> --apply --yes --materialize-version-chain. Engram nunca hace copias de seguridad, modifica ni elimina archivos en tus carpetas de proyecto. Consulta docs/runbooks/setup-upgrade-safety.md.

Comparación

📊 Para la comparación completa, incluyendo cuándo elegir un competidor sobre piia-engram, consulta docs/comparison.md.

Construido Con

piia-engram es un proyecto de código abierto dirigido por humanos y asistido por IA.

Preguntas Frecuentes

¿Qué servidor MCP me permite compartir memoria entre Claude Code y Cursor? piia-engram. Instálalo con pip install piia-engram && engram setup, y ambas herramientas leen la misma identidad, preferencias y lecciones desde ~/.engram/. Sin nube, sin servicio de sincronización: ambas leen archivos JSON locales a través de MCP.

¿Qué es piia-engram? piia-engram es una capa de identidad de trabajo de IA local-first para herramientas de codificación compatibles con MCP. Almacena tu identidad, preferencias, estándares de código, lecciones aprendidas y decisiones clave como archivos JSON locales en tu máquina. Las herramientas configuradas (Claude Code, Codex, Cursor, Windsurf, Claude Desktop) pueden leer el mismo contexto propiedad del usuario, de modo que los nuevos chats y cambios de herramienta pueden comenzar desde la misma base de memoria e identidad gobernada.

¿En qué se diferencia piia-engram del servidor de memoria MCP oficial? El @modelcontextprotocol/server-memory oficial almacena un grafo de conocimiento genérico de entidades y relaciones. piia-engram está especializado en identidad de desarrollador: tiene campos estructurados para tu perfil, estándares de código, nivel de calidad, lecciones aprendidas y decisiones clave, además de 59 herramientas para la gestión del ciclo de vida del conocimiento (búsqueda, revisión, fusión, herencia entre proyectos). Si necesitas memoria de entidades de propósito general, usa el servidor oficial. Si quieres que las herramientas de codificación compatibles con MCP partan de la misma comprensión aprobada de tus preferencias y errores pasados, usa piia-engram.

¿En qué se diferencia piia-engram de herramientas de memoria de agentes como Mem0, Zep o Letta? Esas herramientas almacenan contexto de tareas e historial de sesiones para agentes de IA — lo que ocurrió durante un flujo de trabajo. piia-engram almacena quién eres como persona — tu identidad, preferencias, lecciones ganadas con esfuerzo y decisiones clave. Es una capa diferente: la identidad persiste entre herramientas, sesiones y proyectos, mientras que la memoria de tareas está limitada a una sola ejecución del agente. Tus datos son archivos JSON locales que posees y puedes editar directamente.

¿Por qué no usar simplemente AGENTS.md / CLAUDE.md / .cursorrules? Esos archivos de configuración son excelentes para reglas específicas de repositorio (pasos de compilación, convenciones de codificación). piia-engram es para ti — tus preferencias, lecciones y decisiones que pueden seguirte entre repositorios y herramientas compatibles con MCP configuradas. Se complementan: usa AGENTS.md para el proyecto, piia-engram para la persona. Consulta la comparación completa en docs/comparison.md.

¿Puedo usar piia-engram con varias herramientas de IA a la vez? Sí. Ese es el caso de uso principal. piia-engram usa almacenamiento de archivos local (~/.engram/) con escrituras atómicas y bloqueo de archivos. Claude Code, Cursor, Codex y cualquier otro cliente MCP pueden conectarse simultáneamente. Una lección registrada en Claude Code está disponible inmediatamente en Cursor.

¿Qué herramientas de IA admite piia-engram? Cualquier herramienta compatible con MCP: Claude Code, OpenAI Codex, Cursor, Claude Desktop, Windsurf, GitHub Copilot, Cline, Roo Code, Amazon Q, Augment, Zed y más. Para herramientas sin soporte MCP (ChatGPT, Gemini, Kimi), exporta una tarjeta de identidad Markdown con get_identity_card y pégala.

¿Dónde se almacenan mis datos? Todos los datos viven en ~/.engram/ en tu máquina local como archivos JSON y Markdown simples. Sin nube, sin cuenta, sin suscripción. Puedes abrir, editar, respaldar o migrar los archivos tú mismo. El cifrado opcional AES-256-GCM está disponible mediante pip install piia-engram[secure].

¿Cómo instalo piia-engram?

pip install piia-engram
engram setup

El asistente de configuración detecta tus herramientas de IA sin modificar sus archivos de configuración por defecto. Para auto-configurar entradas MCP con respaldos, ejecuta engram setup --apply-external-config y luego reinicia tu herramienta de IA. La IA llamará a get_user_context al inicio de cada sesión.

Después de actualizar, mi herramienta de IA muestra "servidor MCP desconectado". ¿Cómo lo soluciono? Ejecuta engram doctor --fix en una terminal y luego reinicia tu herramienta de IA. Este comando escanea todos los archivos de configuración MCP conocidos, elimina entradas de servidor obsoletas y repara rutas rotas en un solo paso.

¿piia-engram envía datos a la nube? No por defecto. Las herramientas de identidad y conocimiento usan archivos locales, y la telemetría está desactivada por defecto. Las estadísticas de uso anónimas opcionales pueden habilitarse como registro local; la telemetría remota y los informes de retroalimentación semanales requieren una aceptación explícita separada y envían solo conteos, nunca contenido de conocimiento. Puedes inspeccionar el siguiente payload con engram telemetry preview, desactivar en cualquier momento con engram telemetry off y desactivar el envío remoto con engram telemetry remote off. Consulta PRIVACY.md para el diagrama completo del flujo de datos, qué se recopila y qué no, y tus derechos sobre los datos.

¿Cuántas herramientas MCP proporciona piia-engram? Dos niveles, diseñados para que la mayoría de los usuarios solo vean 18 herramientas:

La mayoría de los usuarios nunca necesitan habilitar las herramientas Avanzadas — el nivel Principal cubre el uso cotidiano.

¿piia-engram es gratuito? Sí. El núcleo de código abierto es software libre bajo AGPL-3.0. El uso personal/local no tiene suscripción, nivel de nube ni bloqueo de proveedor. Si planeas incrustación de código cerrado, redistribución alojada o empaquetado empresarial, revisa primero las obligaciones de AGPL; piia-engram no incluye actualmente una licencia comercial separada.

Limitaciones

piia-engram es funcional y se usa activamente, pero algunas cosas que intencionalmente aún no hace:

Qué significa esto en la práctica:

• No almacenes contraseñas, claves API ni PII de clientes en piia-engram
• Cualquier proceso con acceso de lectura a ~/.engram/ puede leer tus datos
• restricted_fields reduce lo que piia-engram emite en el contexto de arranque en frío, pero no es cifrado ni una ACL real

Esto no es una advertencia para evitar piia-engram — es una descripción honesta de lo que es: una capa de memoria local para contexto personal de IA. Para uso personal, funciona bien hoy.

Configuración de Seguridad

Cifrado a nivel de campo (opcional)

Cifra campos sensibles del perfil (correo electrónico, teléfono, ubicación, etc.) en reposo:

pip install piia-engram[secure]
export ENGRAM_SECRET="your-strong-passphrase"

Los campos cifrados se almacenan como enc:v2:... en archivos JSON; los valores heredados enc:v1:... aún se descifran. Sin ENGRAM_SECRET, piia-engram funciona normalmente con texto plano (compatible hacia atrás).

Registro de auditoría (activado por defecto)

Un registro de auditoría local registra todas las operaciones de lectura/escritura en ~/.engram/audit.log en formato JSON-lines. Es solo un archivo local — nunca se envía a ningún lugar. Consúltalo con la herramienta get_audit_log o grep.

Para excluirte:

export ENGRAM_AUDIT=0

Gobernanza de agentes (avanzada, opcional)

Habilita niveles de confianza por llamador y recibos de divulgación:

export ENGRAM_GOVERNANCE=1
export ENGRAM_CLIENT_TYPE=claude_code

La gobernanza está desactivada por defecto. Cuando está habilitada, los agentes de codificación locales conocidos se filtran a conocimiento público/de trabajo, los llamadores desconocidos fallan cerrados a solo público, y las exportaciones/importaciones/cambios de concesión solo para propietario requieren private-self. Consulta docs/governance.md para los niveles de confianza exactos, compuertas, límites honestos y comandos del libro.

Implementación recomendada: mantén el valor predeterminado global compatible, pero habilita la gobernanza en el entorno de cada cliente MCP cuando uses Engram entre múltiples herramientas de IA, automatización o cualquier puente orientado a remoto. engram status y engram doctor informan si esta capa está activa. La identidad del llamador aún la proporcionan las variables de entorno MCP, no la autenticación criptográfica, por lo que la gobernanza es un límite de política local práctico más que un sandbox endurecido.

Comandos CLI

engram setup            # Interactive install wizard (confirms before writing client configs)
engram setup --apply-external-config  # Skip the confirm prompt (non-interactive/CI); writes with backups
piia-engram doctor           # Check config health + governance state
piia-engram status           # Redacted install + memory/governance summary
piia-engram status --html    # Write a local redacted status page
piia-engram preview          # Show what a simulated AI caller would receive (--as ROLE, --level, --html)
piia-engram continuity       # Prove cross-tool handoff readiness (metadata only)
piia-engram management       # Show a metadata-only review/playbook management view
piia-engram doctor --fix     # Auto-repair any issues found
piia-engram sessions         # List saved cross-tool agent sessions
piia-engram sessions show <id>  # Print one saved session
piia-engram review           # List staging knowledge awaiting review
piia-engram review show <id> # Inspect one review item
piia-engram review approve <id> --yes  # Promote a staging item
piia-engram review archive <id> --yes  # Archive a review item
piia-engram management action review approve <id> --yes --json  # Structured metadata-only action receipt
piia-engram management action playbook delete <id> --yes --json # Soft-delete a Playbook without body echo
piia-engram management action playbook_scope accept_project <id> --project . --yes --json # Resolve ambiguous Playbook scope
piia-engram management action playbook_scope accept_shared <id> --project ./app-a --project ./app-b --yes --json # Share one Playbook with selected projects
piia-engram dock-status      # Zero-write Dock owner-console status (--json)
piia-engram repair-encoding  # Dry-run scan for garbled / mojibake text
piia-engram repair-encoding --apply  # Repair reversible cases with a backup
piia-engram backup-plan      # Metadata-only plan of what to copy before upgrading (local-only)
piia-engram export-agents-md # Export verified, non-sensitive knowledge as an AGENTS.md/CLAUDE.md block
piia-engram stats            # Show project growth metrics (GitHub + PyPI)
piia-engram stats --log      # Append stats snapshot to local log
engram telemetry        # Manage anonymous usage statistics
engram privacy          # Show what data piia-engram stores and where

Contribuciones

Las contribuciones, problemas y comentarios son bienvenidos.

Consulta CONTRIBUTING.md.

Licencia

AGPL-3.0. piia-engram es software libre. Tu identidad de trabajo de IA y tu memoria te pertenecen.