Flema Engram para OpenCode y Pi

Una integración local-first y de solo lectura que mantiene visible el contexto reciente de Engram mientras trabajás dentro de OpenCode o Pi/Gentle Shell.

La canción “Y aún yo te recuerdo” inspiró artísticamente la idea central: que la última memoria guardada siga presente en el contexto de desarrollo. Esta referencia es un homenaje a esa inspiración; no implica afiliación, patrocinio ni titularidad sobre la obra.

English summary: Flema Engram is a local-first, read-only OpenCode and Pi integration that surfaces Engram health, project context, recent memories, blockers, and ODD task progress by default. An MCP stdio adapter is included only as an optional integration path.

Inicio rápido — 0.4.0

Elegí el registro en tui.json para OpenCode o la instalación Pi / Gentle Shell. No hace falta una instalación global npm para ninguno de los viewers.

Requisitos

1. Registrá el sidebar en tui.json

Configuración mínima:

{
  "$schema": "https://opencode.ai/tui.json",
  "plugin": ["opencode-flema-engram-sidebar@0.4.0"]
}

Fijá una versión exacta. OpenCode 1.18.x conserva paquetes npm en caché y una entrada sin versión o con @latest puede seguir resolviendo una release anterior después de que npm publique otra. El plugin no puede actualizarse a sí mismo porque OpenCode lo resuelve e importa antes de ejecutar su código.

Para ubicar el archivo global, ejecutá opencode debug paths y abrí tui.json dentro de la ruta config. Una vez guardado, cerrá completamente OpenCode y abrí un proceso nuevo para que el plugin se cargue.

Diagnosticar y actualizar una instalación

La CLI de mantenimiento consulta las rutas que informa OpenCode, inspecciona la configuración y compara los wrappers de caché con npm sin mostrar opciones del plugin:

npx --yes --package opencode-flema-engram-sidebar@latest flema-engram doctor

Previsualizá siempre la actualización. --dry-run no cambia archivos:

npx --yes --package opencode-flema-engram-sidebar@latest \
  flema-engram update --dry-run

Luego cerrá OpenCode y aplicá el mismo plan:

npx --yes --package opencode-flema-engram-sidebar@latest \
  flema-engram update

La CLI pide una confirmación, respalda tui.json, invoca el instalador oficial con la versión npm exacta y un límite de 60 segundos, elimina solamente wrappers obsoletos que conservan el mismo manifiesto observado en el preview y verifica el resultado. Si el instalador agota ese límite, la CLI lo detiene por la fuerza e informa la ruta exacta del backup retenido. Para automatización controlada, flema-engram update --yes omite únicamente la pregunta: conserva el preview, las validaciones y el backup. --json produce una salida estructurada.

OpenCode 1.18.x no actualiza confiablemente una entrada sin versión o con @latest. OpenCode 2 dispone además de opencode plugin check y opencode plugin update; la CLI usa la sintaxis nativa correspondiente a la versión detectada.

Usando opencode attach

La configuración incluye detección del host de opencode attach <url> para intentar consultar Engram en el puerto 7437, pero no crea túneles ni expone el servicio remoto. La conectividad debe existir desde el proceso que carga el viewer; el loopback remoto no es accesible automáticamente desde otra máquina. Configurá baseUrl explícitamente si la detección no representa tu endpoint y comprobá su /health desde ese proceso. No se garantiza compatibilidad con todas las topologías attach, proxies o URLs.

Usá una versión exacta: attach también puede reutilizar paquetes en caché. La línea 🔌 Target: Local=… | Cloud=… informa los destinos configurados; no prueba una sincronización ni garantiza que ambos respondan. No expongas el puerto de Engram sin controles de acceso.

2. Iniciá Engram y abrí OpenCode en tu proyecto

El sidebar hace una carga inicial, vuelve a consultar cada 30 segundos de forma predeterminada y permite refrescar manualmente con Alt+R.

Viewer para Pi / Gentle Shell

El mismo paquete incluye una extensión Pi de solo lectura. Para Pi convencional, instalá la versión exacta compatible con esta documentación:

pi install npm:opencode-flema-engram-sidebar@0.4.0

Gentle Shell usa un home de paquetes aislado. Instalá allí la misma versión:

PI_CODING_AGENT_DIR="$HOME/.gentle-shell/agent" \
  pi install npm:opencode-flema-engram-sidebar@0.4.0

En Gentle Shell fullscreen, la extensión participa del rail lateral sin reemplazar el status existente. El panel empieza visible y expandido, con marco redondeado: el borde usa el color semántico border y el título accent del theme activo. Un clic izquierdo en el título colapsa o expande el panel, igual que el comando. Muestra proyecto, salud, progreso ODD, bloqueos y actividad reciente. En Pi sin el rail de Gentle Shell usa un overlay pasivo a la derecha cuando el terminal tiene ancho suficiente. Los comandos de presentación son independientes:

/engram-refresh          # Refrescar datos y status; notificar el resultado
/engram-sidebar          # Mostrar u ocultar el sidebar
/engram-sidebar-collapse # Colapsar o expandir el sidebar
/engram-widget           # Mostrar u ocultar el widget debajo del editor

El widget compacto empieza oculto en cada sesión y su visibilidad no se persiste. El sidebar y el widget refrescan al iniciar, reanudar o recargar una sesión y después de que mem_save (o el alias save_memory) termina correctamente. Ocultar cualquiera de las dos vistas no detiene el controller ni desactiva /engram-refresh.

No usa polling periódico y no agrega herramientas para escribir memorias. En modos sin UI no consulta Engram ni intenta renderizar componentes terminales. En RPC no monta el rail ni el overlay terminal.

Para el endpoint principal, definí ENGRAM_URL o ENGRAM_BASE_URL; sin configuración se usa http://127.0.0.1:7437 (el factory compartido también reconoce argumentos attach). La configuración cloud compartida se describe en Seguridad y enfoque local-first. ENGRAM_PROJECT puede fijar el candidato de proyecto; de lo contrario se valida el nombre del directorio actual contra Engram. Los fallos de inicialización se contienen en un estado Engram unavailable sin mostrar URLs, tokens ni diagnósticos con credenciales.

Para desarrollo local, después de compilar el paquete:

npm run build
pi --extension ./dist/pi.js

Qué es — y qué no es

Los viewers de OpenCode y Pi son las integraciones visuales principales. El comando MCP existe para integraciones avanzadas y puede ignorarse por completo al usar cualquiera de los viewers.

Cómo funciona

1. OpenCode carga el export raíz de opencode-flema-engram-sidebar.
2. El plugin resuelve un candidato de proyecto, lo prueba primero con una consulta acotada por proyecto y conserva la enumeración reciente como fallback.
3. Consulta en paralelo salud, proyectos y observaciones del proyecto.
4. Deriva tareas ODD desde espejos canónicos odd/<feature>/tasks, ordena la actividad por actualización y reconoce bloqueos explícitos.
5. Renderiza texto dentro del sidebar de la sesión visible y conserva datos útiles como STALE si una actualización posterior queda incompleta.

Las llamadas usan exclusivamente GET contra los endpoints Engram configurados. Los viewers no guardan, editan ni eliminan memorias.

Endpoints utilizados

El adaptador local y los guards de cada etapa usan un timeout de 5 segundos, salvo que timeoutMs configure otro presupuesto común. Para mantener la vista acotada, el sidebar solicita hasta 20 observaciones del proyecto; si la respuesta filtrada está vacía o mezcla proyectos, usa una consulta sin filtro de hasta 100 registros y aplica una coincidencia exacta local.

Configuración

Opciones soportadas por el plugin

Usá la forma [plugin, options] solamente cuando necesites opciones:

{
  "$schema": "https://opencode.ai/tui.json",
  "plugin": [
    [
      "opencode-flema-engram-sidebar@0.4.0",
      {
        "enabled": true,
        "project": "mi-proyecto",
        "pollInterval": 30000,
        "baseUrl": "http://127.0.0.1:7437",
        "timeoutMs": 5000
      }
    ]
  ]
}

La precedencia del endpoint local es baseUrl explícito, ENGRAM_URL, ENGRAM_BASE_URL, host detectado de opencode attach y, finalmente, loopback. Un timeoutMs ausente o inválido conserva el valor predeterminado de 5 segundos.

Resolución del proyecto

La precedencia real es:

1. project no vacío en el tui.json que declara el plugin;
2. variable de entorno ENGRAM_PROJECT no vacía;
3. nombre normalizado del directorio de trabajo y, como segundo candidato automático, su ruta absoluta normalizada.

$env:ENGRAM_PROJECT = "mi-proyecto"
opencode .

Cada candidato debe coincidir con un proyecto conocido por Engram. Se acepta una coincidencia exacta o una única coincidencia sin distinguir mayúsculas. Un valor explícito o de entorno inválido no cae silenciosamente al nombre del directorio. Tampoco hay búsqueda difusa, recorrido de directorios padre, selector ni elección automática del primer proyecto.

Tema

El render del plugin usa el color de texto del tema activo que entrega OpenCode y no impone una paleta ni crea archivos de tema propios. Los estados también se distinguen por etiquetas e iconos, no solamente por color.

Qué muestra el sidebar

Health

Los fallos muestran la etapa o endpoint relevante. Un error queda contenido en el sidebar para no derribar el host de OpenCode.

Proyecto y contexto detectado

Muestra el nombre validado del proyecto o unresolved. Cuando no puede resolverlo, explica si falta configuración, el candidato no existe, es ambiguo o Engram estaba offline durante la validación.

Observaciones indexadas

La línea Indexed observations refleja las observaciones del proyecto cargadas para la vista actual, dentro del límite acotado del sidebar; no debe interpretarse como un contador histórico total de toda la base. Si no hay registros, se muestra un estado vacío explícito.

ODD Progress

The sidebar derives ODD state from full feature-document mirrors whose topic_key is odd/<feature>/tasks. Each feature shows explicit task counts: done out of total, cancelled, in progress, blocked, and pending. Cancelled tasks are reported separately, not counted as done. See the ODD state contract for the canonical checklist format and newest-valid-document selection. This shared ODD contract also applies to Pi; the legacy workflow commands below are OpenCode-only.

This is a bounded recent-observation view (up to 20 canonical project observations), not a complete project inventory. ODD derivation uses that entire window, not just the five-item activity feed. Invalid mirrors produce a visible diagnostic summary; they never trigger an SDD fallback. When no valid features are available, the empty state explains where to mirror feature documents.

The default sidebar does not derive or render SDD progress. The expanded sidebar shows the current workflow mode. Use the explicit Engram commands in OpenCode:

• Enable legacy SDD for this session (engram.workflow.legacy-sdd) shows the existing SDD phase progress instead of ODD progress, derived from the entire retained bounded observation window rather than the five-item activity feed.
• Return this session to ODD (engram.workflow.odd) immediately clears SDD progress and restores ODD progress without a network refresh.

The choice applies only to the current session, survives sidebar remounts within the same plugin instance, and does not affect other sessions. It is not persisted: every new plugin instance starts in ODD. Invalid ODD mirrors never enable legacy mode automatically. Sidebar session mode is independent of the MCP request-level legacy opt-in described below.

Bloqueos

Lista títulos de observaciones de tipo blocker, o de otras observaciones con blocked en el título o frases explícitas como status: blocked, blocker:, blocked by, depends on o waiting for. Las observaciones session_summary se excluyen de esas heurísticas de título y contenido: un resumen histórico no es un bloqueo activo. Los registros de tipo blocker siguen contando. No infiere bloqueos a partir de sentimiento o contexto ambiguo.

Actividad reciente

Muestra los títulos de las cinco observaciones más recientes del proyecto, ordenadas por updated_at y luego por ID. Cuando no hay actividad, aparece un estado vacío.

Última memoria guardada

No existe un panel duplicado para “última memoria”: la observación actualizada más reciente ocupa el primer lugar de Recent Activity. La vista muestra su título, no el contenido completo. Así mantiene presente la referencia más nueva sin convertir el sidebar en un explorador de memorias.

Refresh, carga y errores — OpenCode

Pi no usa este polling ni estos atajos: refresca por eventos y con /engram-refresh, que actualiza el status y notifica Engram refreshed o Engram refresh incomplete. Las reglas de vista acotada y datos STALE son compartidas.

• La primera carga se agenda una sola vez para el sidebar de la sesión visible.
• El polling automático usa pollInterval o 30 segundos.
• Alt+R vuelve a resolver el proyecto y repite todas las consultas.
• La tecla r sin modificadores queda libre para escribir en el prompt.
• Refreshing…, Refreshed y Refresh incomplete describen el resultado manual.
• Last-good ODD features and diagnostics remain visible as STALE only for the same resolved project; changing or losing project resolution clears them.
• Projects without observations, valid ODD features, or explicit blockers have useful empty states distinct from connection failures.

Ejemplos de uso

Detección automática desde el directorio

cd mi-proyecto
opencode .

Si Engram conoce mi-proyecto, el sidebar valida ese nombre y carga sus memorias.

Fijar un proyecto por workspace

{
  "$schema": "https://opencode.ai/tui.json",
  "plugin": [
    ["opencode-flema-engram-sidebar@0.4.0", { "project": "backend-api" }]
  ]
}

Esto es útil cuando el nombre del directorio no coincide con el proyecto guardado en Engram. El valor debe coincidir; una configuración incorrecta queda como unresolved.

Reducir la frecuencia de actualización

{
  "$schema": "https://opencode.ai/tui.json",
  "plugin": [
    ["opencode-flema-engram-sidebar@0.4.0", { "pollInterval": 60000 }]
  ]
}

El sidebar actualizará cada 60 segundos y seguirá aceptando Alt+R.

Instalación desde el código fuente

git clone https://github.com/oniricosistemas/flema-engram.git
cd flema-engram
npm install

El archivo versionado tui.example.json es la referencia para desarrollo desde el código fuente y apunta directamente a:

{
  "$schema": "https://opencode.ai/tui.json",
  "plugin": [["./src/sidebar/plugin.tsx", {}]]
}

Creá tu copia local con Copy-Item tui.example.json tui__.json en PowerShell o cp tui.example.json tui__.json en shells compatibles. tui__.json está ignorado por Git a propósito: es la copia local para adaptar sin versionar rutas u opciones específicas de tu máquina. Si tu entorno requiere el nombre tui.json, copiá allí el contenido de tui__.json o fusioná su bloque plugin en tu configuración existente.

La ruta se resuelve desde el archivo que declara el plugin. En una configuración global de Windows, reemplazá la ruta relativa de tu copia local por una URL absoluta:

{
  "$schema": "https://opencode.ai/tui.json",
  "plugin": [
    ["file:///D:/general/mcp-flema-engram/src/sidebar/plugin.tsx", {}]
  ]
}

Preservá el resto de tus plugins y opciones al fusionar la configuración.

Solución de problemas

Engram aparece offline

• Confirmá que Engram escuche en 127.0.0.1:7437 o en el endpoint declarado por baseUrl.
• Probá <baseUrl>/health desde el proceso o máquina que carga el viewer.
• Revisá firewalls, proxies y los destinos de Target. El cloud solo se consulta si está configurado; no es una alternativa automática garantizada al endpoint local.
• Si una red o puente responde lentamente, aumentá timeoutMs; el mismo valor limita requests HTTP y etapas del refresh.
• Una URL que no use http: o https: se rechaza dentro del sidebar con un diagnóstico acotado, sin exponer credenciales incluidas en el valor configurado.
• Corregí la causa y presioná Alt+R.

El proyecto no se detecta

• Verificá el nombre real guardado en Engram.
• Definí project en tui.json si el workspace tiene otro nombre.
• Usá ENGRAM_PROJECT solamente cuando deba aplicar al proceso completo.
• Recordá la precedencia: project explícito gana sobre ENGRAM_PROJECT.
• Un proyecto sin observaciones ni sesiones recientes puede no aparecer en la lista derivada que se usa para validarlo.

Los datos parecen viejos

• Mirá si Health dice STALE y leé el detalle de etapa/endpoint.
• En OpenCode esperá el próximo polling o usá Alt+R; en Pi usá /engram-refresh (no hay polling).
• Confirmá que la memoria pertenece exactamente al proyecto resuelto.
• El feed solo muestra cinco títulos y la consulta del sidebar está acotada a 20 observaciones.

El plugin no carga

• Cerrá y reiniciá OpenCode después de cambiar tui.json.
• Validá el JSON y la ruta del plugin.
• Confirmá Node.js 22+ y OpenCode 1.18.25+.
• Para npm, usá opencode-flema-engram-sidebar@<version> con una versión publicada exacta.
• Para fuente local, ejecutá npm install y comprobá que la ruta termine en src/sidebar/plugin.tsx.
• Revisá la salida de arranque de OpenCode. El plugin no crea archivos de log propios.

El sidebar muestra una versión anterior

1. Cerrá todos los procesos OpenCode.

2. Ejecutá opencode debug paths y anotá las rutas config y cache.

3. Confirmá que config/tui.json use opencode-flema-engram-sidebar@<version>.

4. Instalá de nuevo esa versión exacta:

   opencode plugin opencode-flema-engram-sidebar@<version> --force --global

5. Si el sidebar todavía muestra la release anterior, inspeccioná dentro de cache/packages los wrappers opencode-flema-engram-sidebar@*. Eliminá solamente el wrapper obsoleto opencode-flema-engram-sidebar@latest después de confirmar que su node_modules/opencode-flema-engram-sidebar/package.json contiene la versión vieja. Conservá el wrapper exacto y repetí el comando anterior.

6. Abrí un proceso OpenCode nuevo; los procesos existentes no recargan plugins.

En PowerShell, reemplazá <old-version> por la versión anterior que esperás borrar. El comando se niega a eliminar el wrapper si su manifiesto contiene otro valor:

$cache = (opencode debug paths | Select-String '^cache\s+').Line -replace '^cache\s+', ''
$stale = Join-Path $cache 'packages\opencode-flema-engram-sidebar@latest'
$manifest = Join-Path $stale 'node_modules\opencode-flema-engram-sidebar\package.json'
$staleVersion = (Get-Content -LiteralPath $manifest -Raw | ConvertFrom-Json).version
if ($staleVersion -ne '<old-version>') { throw "Refusing to remove wrapper: found $staleVersion" }
Remove-Item -LiteralPath $stale -Recurse -Force

En shells POSIX, reemplazá <cache> y <old-version> por los valores confirmados:

stale='<cache>/packages/opencode-flema-engram-sidebar@latest'
manifest="$stale/node_modules/opencode-flema-engram-sidebar/package.json"
stale_version="$(node -e 'const fs = require("node:fs"); console.log(JSON.parse(fs.readFileSync(process.argv[1], "utf8")).version)' "$manifest")"
[ "$stale_version" = '<old-version>' ] || {
  printf 'Refusing to remove wrapper: found %s\n' "$stale_version" >&2
  exit 1
}
rm -rf -- "$stale"

No borres el directorio completo de caché: puede contener otros plugins, servidores de lenguaje y modelos descargados.

OpenCode no encuentra el export del paquete

• Confirmá que la versión instalada tiene un export raíz por defecto con id y tui.
• Ejecutá npm view opencode-flema-engram-sidebar exports para inspeccionar la metadata publicada.
• Si trabajás sobre un tarball local, verificá que incluya dist/index.js, dist/sidebar/plugin.js y sus declaraciones.
• Usá opencode-flema-engram-sidebar en la configuración. El subpath /tui queda disponible para imports directos, pero OpenCode 1.18.25 puede no cachear ese spec de npm de forma confiable.

Diagnóstico para contribuidores

npm run typecheck
npm test
npm run verify:package

typecheck valida TypeScript sin emitir archivos; test ejecuta Vitest una vez; y verify:package inspecciona un npm pack --dry-run contra el contenido compilado existente. No hay una opción de log JSONL ni un archivo de diagnóstico del sidebar.

Desarrollo y contribución

npm ci
npm run typecheck
npm test
npm run build
npm run verify:package

La CI usa Node 22 y ejecuta, en este orden: typecheck, tests, build y verificación del paquete. No publica artefactos ni necesita secretos. Antes de proponer un cambio:

• Mantené el sidebar como producto principal y el MCP como integración opcional.
• No introduzcas escrituras sobre Engram en el flujo de solo lectura.
• Agregá o actualizá pruebas para cambios de comportamiento.
• Ejecutá los cuatro checks de CI.
• No incluyas src, tests, OpenSpec, configs locales ni logs en el tarball.

Empaquetado y publicación

La lista files permite publicar dist, README.md y LICENSE; npm agrega además la metadata obligatoria. El verificador exige, como mínimo:

• API raíz: dist/index.js y dist/index.d.ts;
• plugin OpenCode (./tui): dist/sidebar/plugin.js y dist/sidebar/plugin.d.ts;
• controller compartido (./core): dist/core.js y dist/core.d.ts;
• extensión Pi (./pi): dist/pi.js y dist/pi.d.ts, registrada en pi.extensions;
• panel Pi: dist/pi/sidebar.js y dist/pi/sidebar.d.ts;
• CLI de mantenimiento flema-engram: dist/maintenance.js;
• MCP opcional mcp-flema-engram: dist/stdio.js;
• README.md, LICENSE y package.json.

docs/ y site/ no se incluyen en npm; las referencias de documentación apuntan al repositorio público.

prepublishOnly ejecuta automáticamente:

npm run typecheck && npm test && npm run build && npm run verify:package

Para publicar necesitás permisos sobre opencode-flema-engram-sidebar, una sesión npm válida y un package.json con versión todavía no publicada. Este repositorio no configura publicación automática, tokens ni secretos.

Integración MCP opcional

Sección avanzada: no es necesaria para usar el sidebar.

La instalación global expone el comando stdio:

mcp-flema-engram

Desde el repositorio puede iniciarse sin compilar con:

npm run mcp

Ejemplo de configuración local de OpenCode, equivalente a opencode.example.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "engram": {
      "type": "local",
      "command": ["npm", "run", "mcp"],
      "enabled": true
    }
  }
}

The server offers read-only MCP tools and resources for health, projects, observations, sessions, ODD state, and explicit legacy SDD access. It uses the same Engram HTTP configuration (loopback by default), without adding persistence or cloud synchronization.

ODD-first project state and explicit legacy access

Call engram_get_project_state with an exact project name:

{ "project": "backend-api" }

The response always includes odd: { bounded: true, features, diagnostics }, derived from canonical odd/<feature>/tasks feature-document mirrors in the loaded exact-project observation window. Existing project metadata, observation counts, explicit blockers, and recent activity remain available. Invalid mirrors stay visible as diagnostics and never cause SDD fallback. Counts and derived workflow state describe bounded recent observations, not an exhaustive inventory or historical total. See the ODD state contract.

includeLegacySdd is an optional boolean, defaulting to false. By default the tool does not derive legacy SDD or expose changes. To add legacy SDD changes to the same ODD response for one request:

{ "project": "backend-api", "includeLegacySdd": true }

This request-scoped opt-in neither reads nor changes the sidebar's session-scoped workflow mode. Dedicated engram://changes, engram://changes/{change_name}/state, and engram://changes/{change_name}/artifacts resources remain operational as explicit legacy SDD access, independently of OpenCode session state. Their results are also limited to the adapter's recent-observation window; other resource behavior is unchanged.

Seguridad, privacidad y enfoque local-first

• Por defecto el viewer consulta loopback; no requiere un servicio cloud ni telemetría.
• Un endpoint remoto explícito o detectado por attach implica tráfico de red: los datos no están necesariamente limitados a esta máquina.
• El factory compartido puede agregar lecturas cloud si encuentra ENGRAM_CLOUD_URL o configuración en ~/.engram/cloud.json. Puede usar ENGRAM_CLOUD_TOKEN o ENGRAM_TOKEN como Bearer token; revisá esa configuración antes de asumir un runtime exclusivamente local.
• No ejecuta operaciones de escritura sobre memorias.
• No crea logs propios con contenido de observaciones.
• El contenido de memorias puede ser sensible: protegé el acceso al proceso y puerto local de Engram como protegerías cualquier herramienta de desarrollo.
• Instalar desde npm y abrir documentación también puede requerir conexiones externas.

El adaptador cloud implementa lecturas HTTP y puede combinarse con el local; no es un servicio alojado ni un mecanismo de sincronización. No se promete seguridad de transporte para despliegues arbitrarios: el adaptador cloud permite certificados TLS no verificados por defecto. Preferí loopback o una red controlada y no envíes tokens a destinos no confiables.

Roadmap y alcance diferido

Están explícitamente fuera del MVP actual:

• dashboard visual y acciones/atajos para abrirlo;
• túneles automáticos y compatibilidad garantizada con cualquier despliegue attach;
• selector manual de proyecto, navegación j/k y más atajos globales;
• sincronización cloud y edición de memorias.

Licencia y enlaces

Distribuido bajo la licencia MIT.

• Repositorio
• Issues
• Paquete npm
• CI