🧠 ai-workspace

Contexto, conocimiento y memoria con demanda progresiva para cualquier workspace de agentes IA.

Tu OpenCode, Codex, agy o Claude Code dejan de re-leer 60 KB de docs obsoletas en cada sesión: un Context Broker MCP les da exactamente el contexto que necesitan, cuando lo necesitan.

El problema que resuelve

Cada agente nuevo (o cada sesión) recibe el mismo trato: documentación duplicada, obsoleta, dispersa — PLAN-FINAL-v3.md, CONTINUATION-2.md, AUDIT-5.md, HANDOFF-final-FINAL.md… El agente quema miles de tokens leyendo irrelevancia, olvida decisiones tomadas hace dos días y repite errores ya resueltos.

ai-workspace convierte el workspace en un sistema autoorganizado de 5 niveles (GLOBAL → WORKSPACE → PROJECT → FEATURE → SESSION) con recuperación bajo demanda: el agente arranca con ~4 KB de reglas y pide el resto por tools del broker.

AGENTE: «¿qué repos toco para 'conectar programas del ERP con la app'?»
BROKER: get_dependencies → { repos: [back, front, app] }      ← 3 tokens de respuesta, no 60 KB de docs
AGENTE: read_doc("workspace/OVERVIEW.md")                      ← solo si necesita el estado

Related MCP server: Sugar

⚡ Instalación en 30 segundos

Opción A — un comando (desde la raíz de tu proyecto o workspace):

npx github:LFDIAZDEV2209/ai-workspace

Opción B — con un prompt a tu agente (él solo ejecuta todo):

Lee https://github.com/LFDIAZDEV2209/ai-workspace/blob/main/AGENT-INSTALL.md
y ejecuta exactamente lo que indica.

Qué hace el instalador (idempotente, nunca pisa tus ficheros):

1. Crea .ai/ en tu workspace desde la plantilla (broker, memoria, playbooks, gobernanza).

2. Siembra memory.db (SQLite + FTS5, zero deps — solo requiere Node ≥ 22.5).

3. Registra el MCP context-broker en OpenCode (y en Codex/agy con --codex --agy).

4. Verifica con un health check y te deja el prompt final para que tu agente rellene el contenido con los datos reales de tu proyecto.

# Flags
npx github:LFDIAZDEV2209/ai-workspace            # OpenCode + scaffold + seed global
npx github:LFDIAZDEV2209/ai-workspace --codex    # + Codex (config.toml)
npx github:LFDIAZDEV2209/ai-workspace --agy      # + agy (Antigravity CLI)
npx github:LFDIAZDEV2209/ai-workspace --no-mcp   # solo scaffold de .ai/ (sin registro ni seed)
npx github:LFDIAZDEV2209/ai-workspace --no-seed  # registra MCP pero sin lecciones semilla

📦 Los 4 casos de uso

🔍 Cómo funciona (30 segundos)

~/.ai-workspace/global/  ← store GLOBAL de la máquina: knowledge cross-proyecto (todos los brokers lo leen)
.ai/
  broker/broker.mjs      ← Context Broker MCP (stdio, JSON-RPC 2.0, zero-dep node:sqlite)
  memory/memory.db       ← SQLite WAL + FTS5: lessons · decisions · incidents · patterns · handoffs
  workspace/             ← canónicos vivos (~5 KB c/u): OVERVIEW · PROJECTS · ROUTER · AGENT-MATRIX · OPEN-ITEMS
  knowledge/             ← texto canónico estructurado (1 fichero = 1 entrada, indexado por README)
  playbooks/             ← onboarding · QA · orquestación (Herdr) · release
  scripts/               ← session-close (learning pipeline) · doc-health (stale/duplicados/drift)

• Arranque frío: el agente lee ~4 KB de AGENTS.md y pide lo demás al broker (workspace_overview, get_dependencies, search_knowledge, read_doc… — 15 tools).

• Aprendizaje entre proyectos: una lesson/decisión con scope: GLOBAL se escribe en el store global de la máquina y aparece marcada [global] en las búsquedas de cualquier otro proyecto de ese PC — el agente del repo B aprende lo que el agente del repo A documentó. La primera instalación siembra 5 lecciones universales (MCP stdio, reconexión, encoding Windows, WAL multi-agente, servidores en background): tus agentes nacen con conocimiento probado y lo acumulan con tu trabajo. Demo real: una lesson nacida en un workspace fue encontrada por el broker de otro proyecto en otra ruta con su memoria local vacía.

• Cierre de sesión: node .ai/scripts/session-close.mjs registra el handoff y emite el checklist (OVERVIEW, OPEN-ITEMS, índices, commits).

• Higiene continua: doc-health detecta docs de sesión sueltas, canónicos >12 KB, stale >45 días, títulos duplicados, ficheros sin indexar y drift contra la plantilla global.

Arquitectura completa: docs/HOW-IT-WORKS.md

🤖 Agentes soportados

| Prueba de fuego documentada: agentes nuevos sin contexto previo respondieron

4/4 preguntas del workspace (repos, routing de tarea, comandos de build/test, bloqueos de TestFlight) usando únicamente este sistema — en 3 motores distintos.

🔧 Uso sin MCP (CLI directo)

node .ai/broker/broker.mjs overview            # resumen del workspace
node .ai/broker/broker.mjs router "<tarea>"    # ¿qué repos involucra?
node .ai/broker/broker.mjs search "<keywords>" # lessons/decisions/handoffs
node .ai/broker/broker.mjs health              # salud de la memoria

🩺 Troubleshooting

Los errores reales que sufrimos (y su solución) están en docs/TROUBLESHOOTING.md: MCP "Request timed out" (frames sin envelope JSON-RPC 2.0), warning experimental de node:sqlite (inofensivo, va a stderr), mojibake en Windows (UTF-8 sin BOM + PS 5.1), concurrencia WAL multi-agente, paths de Codex/agy.

📚 Docs

• docs/HOW-IT-WORKS.md — arquitectura, niveles, broker, memoria, pipeline

• docs/USE-CASES.md — los 4 casos con prompts listos

• docs/PROMPTS.md — 10 prompts copia-pega para tu agente

• docs/TROUBLESHOOTING.md — fallos reales y solución

• AGENT-INSTALL.md — el prompt de instalación para tu agente

🛣️ Roadmap

• sqlite-vec opcional (vector search) — el schema ya reserva la evolución

• Hooks de cierre de sesión automáticos por plugin

• memory.mjs CLI avanzado (stats, GC de sessions EPHEMERAL)

• Dashboard web del estado del workspace

• Publicación en npm registry (npx ai-workspace a secas)

Hecho para que cualquier agente sea inteligente desde el minuto uno. Si te sirvió, deja una ⭐.