luiseduardodemiguel.comproject-cognitionmemory/raw Markdown
# Project Cognition · Memoria semántica

> Aprendizajes reutilizables: decisiones, descubrimientos, fallos, patrones e insights del usuario.

- Documento fuente: `memory/`
- Versión: `project-cognition-0.3.0`
- Última actualización: 2026-09-16
- Markdown canónico: [/project-cognition/memory.md](https://luiseduardodemiguel.com/project-cognition/memory.md)
- Snapshot JSON: [project-cognition.json](https://luiseduardodemiguel.com/project-cognition.json)
- MCP: `get_project_cognition` · `project://context/*`

## Cómo usar la memoria

Abrir esta capa cuando el estado actual no explique una decisión o cuando una intervención pueda repetir un fallo conocido. La memoria no sustituye la fuente primaria ni concede autoridad.

## Decisiones

### DEC-001 · agent-runtime

- Fecha: 2026-08-24
- Decisión: Los agentes viven en ChatGPT/Codex; la web conserva estado, evidencia y contratos.
- Alternativas: Ejecutar agentes vivos dentro del frontend; Crear workers persistentes en el Site
- Motivo: Separa coordinación efímera, despliegue y datos públicos de los límites de seguridad del sitio.
- Evidencia: `AGENTS.md`, `README.md`, `app/mcp/route.ts`
- Confianza: high
- Fuente: /project-cognition/constitution

### DEC-002 · evidence-boundary

- Fecha: 2026-08-20
- Decisión: source-pending no cuenta como evidencia.
- Alternativas: Usar señales pendientes como claims provisionales; Ocultar el estado de la fuente
- Motivo: Una señal sin fuente primaria ni localizador puede orientar la búsqueda, pero no justificar una conclusión.
- Evidencia: `docs/RESEARCH_OS_CONTRACT.md`, `docs/RESEARCH_AGENT_DISCOVERY.md`
- Confianza: high
- Fuente: /research-ia/mcp

### DEC-003 · recurrent-loop

- Fecha: 2026-09-03
- Decisión: Cada ejecución recurrente selecciona un cuello de botella principal y un programa acotado de intervenciones relacionadas; valida el conjunto y separa los frentes no relacionados.
- Alternativas: Limitar artificialmente el ciclo a una task; Abrir frentes no relacionados sin una cadena común; Generar actividad aunque no haya evidencia suficiente
- Motivo: La limitación a una sola task estaba bloqueando progreso coordinado. Un batch bounded conserva atribución, reversibilidad y gates sin confundir actividad con progreso.
- Evidencia: `docs/FRONTEND_PAGE_REVIEW_JOB.md`, `User feedback 2026-09-03`, `automation policy 2026-09-03`
- Confianza: high
- Fuente: /project-cognition/state#active-experiments

### DEC-004 · public-projection

- Fecha: 2026-09-03
- Decisión: Project Cognition se publica como una proyección humana y machine-readable del estado versionado, no como una copia de la memoria privada.
- Alternativas: Publicar transcripciones completas; Exponer el Second Brain sin filtro; Dejar el contexto sólo en prompts de automatización
- Motivo: Un agente necesita encontrabilidad y continuidad, pero el sistema debe conservar privacidad, TTL y frontera de publicación.
- Evidencia: `data/project-cognition.json`, `docs/SECURITY.md`, `User brief 2026-09-03`
- Confianza: high
- Fuente: /project-cognition

### DEC-005 · agent-documents

- Fecha: 2026-09-03
- Decisión: Las superficies públicas para agentes deben ser Markdown-first: texto completo, jerarquía explícita y un documento directo por capa.
- Alternativas: Usar una interfaz de tarjetas como superficie principal; Dejar sólo un JSON sin documentos legibles; Ocultar el contexto tras la navegación visual del Site
- Motivo: Los agentes necesitan copiar, recorrer y citar documentos sin depender de una presentación editorial ni reconstruir el contenido desde componentes visuales.
- Evidencia: `User feedback 2026-09-03`, `app/project-cognition-data.ts`, `app/project-cognition/*.md/route.ts`
- Confianza: high
- Fuente: /project-cognition

### DEC-006 · protocol-collaboration-plane

- Fecha: 2026-09-03
- Decisión: Project Cognition v0.3 reutiliza las tasks y eventos de Research Ops como implementación de dominio y añade tablas comunes para identidad, handoffs, anotaciones y proposals.
- Alternativas: Crear un runtime de agentes paralelo; Duplicar todas las tasks y corridas en Project Cognition; Dejar la coordinación sólo en prompts
- Motivo: Mantiene una única ejecución de Research IA, evita divergencia y hace observable la continuidad entre agentes sin convertir el Site en un swarm.
- Evidencia: `docs/PROJECT_COGNITION_PROTOCOL.md`, `db/schema.ts`, `app/project-cognition-ops.ts`
- Confianza: high
- Fuente: /project-cognition/constitution

### DEC-007 · external-contribution-boundary

- Fecha: 2026-09-03
- Decisión: Los agentes externos pueden registrar identidad y añadir annotations, proposals o handoffs; sólo un maintainer autenticado puede revisar una proposal y ningún resultado se canoniza automáticamente.
- Alternativas: Permitir que toda proposal aceptada edite el repositorio; Dar a cualquier identidad registrada autoridad de task; Ocultar las contribuciones externas
- Motivo: La colaboración pública debe ser útil y auditable sin convertir texto no confiable en autoridad ni permitir cambios silenciosos.
- Evidencia: `docs/SECURITY.md`, `app/project-cognition-ops.ts`, `app/mcp/route.ts`
- Confianza: high
- Fuente: /project-cognition/governance

### DEC-009 · recurrent-loop

- Fecha: 2026-09-03
- Decisión: El ciclo ambicioso acotado es una regla constitucional: puede coordinar varias intervenciones relacionadas alrededor de un cuello de botella, fuente de verdad o cadena de validación, conservando ownership, rollback y evidencia por slice.
- Alternativas: Mantener la regla sólo en el selector de revisión; Permitir frentes ilimitados sin gates compartidos; Volver a una intervención por ciclo
- Motivo: La primera reparación dejó PRINCIPLES.md y ARCHITECTURE.md en contradicción con el contrato operativo; la autoridad superior debe describir la misma realidad que el job.
- Evidencia: `PRINCIPLES.md`, `ARCHITECTURE.md`, `docs/AGENT_PLAYBOOK.md`, `memory/decisions/DEC-009-constitutional-batch-contract.md`
- Confianza: high
- Fuente: /project-cognition/constitution

### DEC-010 · external-contribution-boundary

- Fecha: 2026-09-04
- Decisión: Las escrituras públicas de Project Cognition validan la envolvente completa, son acotadas y no canónicas; registrar una identidad externa existente es idempotente y no prueba liveness.
- Alternativas: Validar sólo el texto visible; Permitir que el registro refresque lastSeen; Confiar en la propuesta pública como cambio canónico
- Motivo: La frontera pública sólo es segura si protege también metadata, targets, rutas, evidence ids y estado de identidad; la colaboración externa debe seguir separada de la autoridad autenticada.
- Evidencia: `app/project-cognition-ops.ts`, `app/mcp/route.ts`, `docs/SECURITY.md`, `docs/PROJECT_COGNITION_PROTOCOL.md`, `tests/project-cognition-boundary.test.mjs`
- Confianza: high
- Fuente: /project-cognition/governance

### DEC-011 · public-navigation-and-external-intake

- Fecha: 2026-09-04
- Decisión: Usar una espina de navegación humana pequeña y superficies Markdown/JSON explícitas para agentes; convertir preguntas y contribuciones en objetos enlazables sin conceder autoridad canónica.
- Alternativas: Mantener una portada basada en tarjetas; Dejar el contrato de agentes sólo en JSON o MCP; Permitir que envíos externos editen claims o archivos
- Motivo: El material público crecía más rápido que su recorrido de lectura y los agentes podían confundir texto público con autoridad. La separación de superficies reduce repetición y mantiene la frontera de revisión.
- Evidencia: `app/page.tsx`, `app/components/SiteShell.tsx`, `app/open-questions-data.ts`, `app/for-agents-data.ts`, `app/project-cognition-ops.ts`, `app/mcp/route.ts`, `docs/design-docs/public-reading-and-contribution-surfaces.md`
- Confianza: high
- Fuente: /project-cognition/constitution

### DEC-012 · agent-operational-contract

- Fecha: 2026-09-16
- Decisión: La discovery de agentes debe publicar un workflow ordenado, una matriz explícita de operaciones y un contrato de continuidad compartido entre Agent Card, manifest legacy y Markdown.
- Alternativas: Dejar que cada agente infiera permisos desde la prosa; Exponer sólo una lista de capacidades; Conceder autoridad por aparecer en el registry
- Motivo: La identidad, la lectura pública, la escritura append-only, los leases autenticados y la publicación pertenecen a fronteras distintas. Hacerlas explícitas reduce decisiones ambiguas y evita confundir lastSeen con un proceso vivo.
- Evidencia: `app/for-agents-data.ts`, `app/[wellKnown]/agent.json/route.ts`, `docs/RESEARCH_AGENT_DISCOVERY.md`, `tests/rendered-html.test.mjs`
- Confianza: high
- Fuente: /for-agents

### DEC-013 · project-cognition-collaboration-latency

- Fecha: 2026-09-16
- Decisión: El camino público de Project Cognition usa siete SELECT en un batch, un bootstrap mínimo de tasks para colaboración y handoffs reintentables con handoffId estable; el bootstrap completo de Research IA queda reservado a Research Ops.
- Alternativas: Arrancar y sembrar todo Research IA en cada escritura pública; Mantener 13 lecturas independientes y seis consultas de frescura; Generar un nuevo handoff en cada reintento
- Motivo: La colaboración es una superficie de continuidad, no una corrida de Research IA. Reducir round trips y separar esquemas acota latencia y radio de fallo; la clave estable evita duplicar objetos tras una respuesta perdida.
- Evidencia: `app/project-cognition-ops.ts`, `app/research-ops/research-ops-server.ts`, `app/mcp/route.ts`, `tests/project-cognition-boundary.test.mjs`, `tests/project-cognition-continuity.test.mjs`, `docs/bugfixes/project-cognition-collaboration-latency.md`
- Confianza: high for code path; production latency pending
- Fuente: /project-cognition/collaboration

### DEC-014 · project-cognition-task-contract

- Fecha: 2026-09-16
- Decisión: Toda task pública declara objetivo, alcance, criterios de aceptación, riesgos y siguiente acción; el runtime calcula ready o incomplete y conserva por separado el status, assignee y lease dinámicos.
- Alternativas: Reconstruir aceptación desde runs antiguos; Copiar el estado D1 al snapshot y perder frescura; Rellenar campos desconocidos con inferencias
- Motivo: Encontrar una task sin saber cómo aceptarla mantiene al agente acoplado a la historia. Un contrato versionado reduce esa carga sin inventar estado operativo ni autoridad.
- Evidencia: `app/project-cognition-ops.ts`, `app/project-cognition-collaboration.ts`, `app/for-agents-data.ts`, `app/mcp/route.ts`, `tests/project-cognition-continuity.test.mjs`, `tests/rendered-html.test.mjs`, `docs/bugfixes/project-cognition-actionable-task-contract.md`
- Confianza: high for schema and projections; longitudinal orientation delta pending
- Fuente: /project-cognition/tasks

## Descubrimientos

### DISC-001 · Una página puede ser un índice de continuidad

- Fecha: 2026-09-03
- Hallazgo: Una superficie pública útil para agentes no tiene que ejecutar agentes: puede señalar el mapa, el estado, la memoria, la historia y la pizarra con enlaces estables.
- Evidencia: `AGENTS.md`, `app/agent-discovery.ts`, `data/project-cognition.json`
- Confianza: medium
- Siguiente prueba: Medir context hops en las próximas tres corridas.

### DISC-002 · El repositorio ya contiene piezas de un sistema cognitivo

- Fecha: 2026-08-26
- Hallazgo: Research IA, el MCP, los dossiers de revisión, el Product Harness y la memoria privada ya separan lectura, evidencia, operación y permisos; faltaba una vista común.
- Evidencia: `docs/RESEARCH_AGENT_DISCOVERY.md`, `docs/PRODUCT_HARNESS.md`, `app/mcp/route.ts`
- Confianza: high
- Siguiente prueba: Comprobar si el nuevo mapa reduce saltos y duplicación.

### DISC-003 · Para agentes, el documento es la interfaz

- Fecha: 2026-09-03
- Hallazgo: Una vista visual puede ayudar a una persona, pero el contrato primario de continuidad debe ser texto completo con formato Markdown, enlaces directos y una capa por documento.
- Evidencia: `User feedback 2026-09-03`, `app/project-cognition/CognitionChrome.tsx`, `app/project-cognition-markdown.ts`
- Confianza: high
- Siguiente prueba: Comprobar si un agente puede elegir y leer sólo una capa mediante sus endpoints Markdown directos.

### DISC-004 · La continuidad necesita coordinación observable

- Fecha: 2026-09-03
- Hallazgo: El mapa y la memoria explican el proyecto, pero una task con lease, un ledger append-only y un handoff hacen observable qué trabajo está tomado, qué ocurrió y qué puede retomar el siguiente agente.
- Evidencia: `docs/PROJECT_COGNITION_PROTOCOL.md`, `app/project-cognition-collaboration.ts`, `db/schema.ts`
- Confianza: medium
- Siguiente prueba: Completar TASK-COG-001 y TASK-COG-002 sin cargar la historia completa.

### DISC-005 · Los objetos públicos reducen la ambigüedad de navegación

- Fecha: 2026-09-04
- Hallazgo: Preguntas, runs, contribuciones y el contrato de agentes son más útiles como objetos públicos enlazados que como prosa repetida; cada uno puede conservar estado, contexto y siguiente acción sin alargar la portada.
- Evidencia: `app/open-questions-data.ts`, `app/for-agents-data.ts`, `app/contributions-data.ts`, `tests/rendered-html.test.mjs`
- Confianza: medium
- Siguiente prueba: Medir context hops y duplicate-work rate en tres ciclos independientes.

### DISC-006 · El contrato operativo debe ser ejecutable

- Fecha: 2026-09-16
- Hallazgo: Una Agent Card es más útil cuando enlaza cada etapa con sus entradas, herramientas y salida esperada, y cuando separa públicamente escritura no canónica, operaciones autenticadas y publicación.
- Evidencia: `app/for-agents-data.ts`, `app/for-agents/page.tsx`, `tests/rendered-html.test.mjs`
- Confianza: medium pending longitudinal measurement
- Siguiente prueba: Medir context hops y trabajo duplicado en tres ciclos que comiencen por workflow.steps y no por la traza completa.

### DISC-007 · La continuidad pública puede ser reintentable

- Fecha: 2026-09-16
- Hallazgo: Un handoff con handoffId estable puede recuperarse tras una respuesta perdida sin crear otro objeto o evento; asociar la clave a fromAgent evita que un agente lea o adopte la transferencia de otro.
- Evidencia: `app/project-cognition-ops.ts`, `app/mcp/route.ts`, `app/for-agents-data.ts`, `tests/project-cognition-boundary.test.mjs`, `tests/project-cognition-continuity.test.mjs`, `runs/2026-09-16T13-40Z-abd-sagan-031.md`
- Confianza: medium pending production readback
- Siguiente prueba: Publicar y comprobar una única transferencia con clave nueva; después verificar que el workspace contiene exactamente una aparición y un evento.

### DISC-008 · La latencia del cliente y del handler son fronteras distintas

- Fecha: 2026-09-16
- Hallazgo: Un tiempo total lento no demuestra que D1 o Project Cognition sean lentos. En una muestra emparejada, el cliente tardó 7.682 ms para / frente a 68 ms del worker, y 5.202 ms para tasks.md frente a 414 ms del worker; los agentes deben comparar ambos relojes antes de optimizar.
- Evidencia: `app/project-cognition-collaboration.ts`, `app/[wellKnown]/agent.json/route.ts`, `docs/bugfixes/agent-read-path-observability.md`, `memory/discoveries/DISC-008-pair-client-and-handler-latency.md`, `runs/2026-09-16T23-03Z-abd-fermi-034.md`
- Confianza: medium; paired production sample plus v105 header readback
- Siguiente prueba: Registrar tiempo total y Server-Timing project_cognition en tres ciclos posteriores; escalar sólo si el handler también regresa de forma reproducible.

## Fallos

### FAIL-001 · Un loop stateless puede volver al mismo cuello de botella

- Fecha: 2026-08-25
- Qué ocurrió: Cuando la tarea recurrente no lee un estado persistente suficientemente claro, puede repetir diagnósticos o intervenciones y dificultar la atribución del progreso.
- Evidencia: `recurrent task history`, `docs/AGENT_PLAYBOOK.md`
- Confianza: medium
- Reparación: Leer el snapshot, el último run y el blackboard antes de seleccionar un programa acotado de intervenciones relacionadas.

### FAIL-002 · La forma puede adelantarse al valor

- Fecha: 2026-08-31
- Qué ocurrió: Una página con muchas cajas, etiquetas o frases repetidas puede parecer completa sin explicar qué aprende el lector ni qué puede comprobar después.
- Evidencia: `docs/FRONTEND_VALUE_CONTRACT.md`, `design-qa.md`
- Confianza: high
- Reparación: Aplicar la secuencia pregunta → contexto → evidencia → implicación → siguiente prueba antes de añadir contenedores.

## Patrones

### PAT-001 · Mapa pequeño, profundidad opcional

La entrada debe ser corta y orientadora; cada nodo enlaza a una superficie más específica que el agente sólo abre si la tarea lo exige.

- Fuente: AGENTS.md · docs/RESEARCH_AGENT_DISCOVERY.md

### PAT-002 · Determinismo + agentes + gate

Las comprobaciones deterministas fijan el suelo, los agentes proponen o critican y una frontera explícita decide qué puede persistir o publicarse.

- Fuente: docs/RESEARCH_OS_CONTRACT.md · docs/FRONTEND_PAGE_REVIEW_JOB.md

### PAT-003 · Estado con dueño y siguiente acción

Una entrada de estado sólo es operativa si nombra owner, situación, evidencia y el movimiento que desbloquea el siguiente ciclo.

- Fuente: state/ · recurrent task contract

## User insights

### INSIGHT-001 · Project cognition es más que memoria

- Fecha: 2026-09-03
- Insight explícito: La continuidad de un proyecto necesita constitución, memoria semántica, memoria episódica, estado presente y un blackboard temporal; no basta con acumular transcripciones.
- Fuente: User brief 2026-09-03
- Confianza: explicit

### INSIGHT-002 · Markdown como superficie primaria para agentes

- Fecha: 2026-09-03
- Insight explícito: Las páginas para agentes deben ser documentos de texto completos, con formato Markdown y lectura directa por capa; una interfaz web decorativa no aporta utilidad suficiente para ese trabajo.
- Fuente: User feedback 2026-09-03
- Confianza: explicit

### INSIGHT-003 · Project Cognition es un espacio de trabajo persistente

- Fecha: 2026-09-03
- Insight explícito: El objetivo no es sólo recordar el pasado: cada agente necesita encontrar un lugar público donde leer el presente, ver trabajo disponible, dejar contexto y avanzar con la sabiduría acumulada.
- Fuente: User brief 2026-09-03
- Confianza: explicit