byblos-dev

Harness de desarrollo instalable: un scaffolder que monta la estructura del harness en cualquier repo y un servidor MCP que le da a tu agente de código memoria propia, buscable y portable, sobre SQLite + FTS5 (+ vectores opcionales). La memoria se auto-carga al arrancar cada sesión (hook SessionStart) — es canónica, no un .md que el agente decide leer o no.

Idea

0. npm i -g byblos-dev@latest   # UNA vez por máquina (ver "Instalar")
1. byblos-dev init        # POR proyecto: monta AGENTS.md, reglas, skills, memoria, hooks, MCP
2. Reiniciás el cliente   # VS Code/Claude Code → MCP conectado + memoria auto-cargada al arrancar
3. byblos-dev import      # (proyecto existente) siembra memoria desde tus docs

Instalar

byblos es una dev-tool de agente (MCP de memoria), no runtime de tu app. Se publica en el registry público de npm, así que no hace falta token, cuenta ni .npmrc.

Setup de máquina (una sola vez)

npm i -g byblos-dev          # instala el motor global
byblos-dev help              # verificá que el CLI responde

Por proyecto

cd <tu-proyecto>
byblos-dev init              # monta el harness; bakea la ruta del motor GLOBAL en hooks + MCP
# reiniciá VS Code / Claude Code → MCP conectado + memoria auto-cargada

El modo global (default) deja el repo sin footprint: init no escribe package.json ni .npmrc — los hooks de git y el server MCP apuntan (ruta absoluta) al byblos global, así CI nunca lo toca. Actualizás el motor para todos tus proyectos con npm i -g byblos-dev@latest (corré byblos-dev update en un proyecto solo si querés refrescar skills o re-bakear sus hooks).

⚠ No commitees los archivos que bakean tu ruta de máquina. En modo global, .husky/post-commit y el hook SessionStart de .claude/settings.json contienen una ruta ABSOLUTA de TU máquina. Gitignorealos (o no los commitees); cada colega corre byblos-dev init y genera los suyos.

Modo --local (equipos que quieren pinear por repo). byblos-dev init --local instala byblos como devDependency (npm i -D byblos-dev — npm público, sin token) y bakea la ruta de node_modules. Útil si querés que el harness viaje con el repo y se pinee en el lockfile. byblos es devDep → no entra al bundle de prod (--production/--omit=dev la saltea).

Comandos

byblos-dev help lista todo en la terminal (también --help, -h). Referencia rápida:

| Comando | Qué hace | Flags | |---|---|---| | init | Monta el harness: AGENTS.md, reglas, skills base, .byblos/memory.db, registro MCP y hooks de git (pre-commit + post-commit). Idempotente (no pisa tus archivos). | — | | adopt | Switch al modelo AGENTS.md agnóstico: mueve el contenido de los archivos por-agente (CLAUDE.md, GEMINI.md, AGENT.md, .github/copilot-instructions.md, .cursorrules, .windsurfrules, .clinerules, .aiderrules, CONVENTIONS.md) dentro de AGENTS.md y los deja como puntero. Solo toca los que existen. No pierde nada, idempotente. | --dry-run | | update | Pone el proyecto al día: refresca las skills sembradas y re-bakea los hooks de git + SessionStart a la ruta del motor actual (global por default; --local imprime el comando devDep). No toca tus skills propias. | --dry-run · --skills-only · --local | | import | Siembra memoria desde markdown (MEMORY.md, docs/adr/**, glosarios) o desde un export JSONL de byblos. Markdown entra proposed salvo --active; un .jsonl entra active. Idempotente (dedup por source). | --dry-run · --active · --file <ruta> --as <decision\|directive\|glossary> · --file <export>.jsonl | | export | Vuelca la memoria vigente del proyecto a un JSONL commiteable (una memoria por línea → git diffea/mergea). Así se comparte la memoria de proyecto entre devs vía git. Idempotente. | --out <ruta> · --scope global · --dry-run | | sync | Atajo: export + git add (solo el jsonl) + commit + push; o --import = git pull --ff-only + import. Stagea solo el .jsonl, salta si no cambió, pull --ff-only. | --import · --no-push · --no-pull · --file <ruta> · --dry-run | | log-commit | Registra un episode del commit HEAD. Lo invoca el hook post-commit; rara vez a mano. | --dry-run | | help | Ayuda en terminal. | --help -h |

El camino

Proyecto nuevo

byblos-dev init           # scaffold completo
# conectá el MCP (abajo) y empezá: la memoria se llena sola con el uso + hooks

Proyecto existente (con docs ya escritos)

byblos-dev init                 # scaffold idempotente: agrega solo lo que falta
byblos-dev adopt --dry-run      # si ya tenías CLAUDE.md: mirá el switch a AGENTS.md
byblos-dev adopt                # consolida en AGENTS.md (agnóstico), CLAUDE.md → puntero
byblos-dev import --dry-run     # mirá QUÉ fuentes detecta antes de escribir
byblos-dev import               # siembra (entra 'proposed' → curás en el chat)
#   …o, si tus ADRs/glosario ya están curados:
byblos-dev import --active      # entran 'active', sin curaduría por-item
#   …para un archivo de nombre no convencional:
byblos-dev import --file docs/notas.md --as glossary

import reconoce por nombre/ubicación: MEMORY.md/feedback* → directive; dirs adr/ o decisions/ (a cualquier nivel) y DECISIONS.md → decision; *glossary*/*glosario* → glossary. El gate por nombre es deliberado: evita volcar docs de diseño/sesión como memoria. Lo que no calce, va por --file … --as … o se cura a mano con la tool memory_write.

Tras un nuevo release del paquete

npm i -g byblos-dev@latest   # actualizá el motor GLOBAL (una vez, sirve a todos los proyectos)
byblos-dev update                               # OPCIONAL por proyecto: refresca skills + re-bakea hooks al motor actual

En modo global el motor es uno solo (el global), así que actualizarlo alcanza para todos tus proyectos. update por proyecto solo hace falta para traer skills nuevas del template o re-bakear los hooks (p. ej. si cambió la ruta del motor). --skills-only salta el re-bake.

Memoria canónica: byblos vs .md

El valor central: byblos se auto-carga al arrancar cada sesión, igual que un .md nativo — pero su memoria es buscable, tipada y crece sin límite. Lo hace el hook SessionStart que instala init: corre byblos-dev session-context y Claude Code inyecta las memorias vigentes (rules, directives, decisions, tasks) al contexto, sin que el agente tenga que invocar nada.

Eso cierra el problema clásico: una memoria que solo se escribe pero nunca se consulta al arrancar es redundante — el agente la ignora y la regla termina en un .md. Con el hook, byblos se consulta solo.

El reparto:

| | Para qué | Cómo se escribe | |---|---|---| | AGENTS.md (.md) | Contexto estable: qué es el proyecto, stack, reglas duras resumidas, puntero | a mano, cambia poco | | byblos (.byblos/memory.db) | Memoria durable que crece: decisiones, lecciones, reglas nuevas, episodios de commits | memory_write (entra proposed → memory_confirm); append-only |

Regla: lo durable y que crece va a byblos (memory_write), no a .md. El encabezado que inyecta el hook se lo recuerda al agente cada sesión.

Nota honesta. Claude Code igual auto-carga CLAUDE.md/AGENTS.md (comportamiento nativo, no se apaga). byblos no reemplaza a .md por la fuerza: lo nivela (ambos auto-cargan) y empuja con la directriz a que la memoria durable viva en byblos. No hay enforcement físico — depende de que el agente respete la directriz, que ahora ve en cada arranque.

Compartir memoria de equipo (vía git)

La DB (.byblos/memory.db) es local y NO se trackea (binario → git no puede diffear ni mergear; dos devs escribiendo = conflicto irresoluble + memoria perdida). Para compartir memoria de proyecto entre devs se usa un export JSONL (texto, una memoria por línea → git diffea y mergea por línea):

# dev A: vuelca la memoria activa del proyecto y la commitea
byblos-dev export                    # → .byblos/memory.export.jsonl
git add .byblos/memory.export.jsonl && git commit -m "chore(memory): sync byblos"

# dev B: tras pull, la sincroniza en su DB local
byblos-dev import --file .byblos/memory.export.jsonl

Atajo sync — une export/import con git en un comando:

byblos-dev sync            # export + git add (solo el jsonl) + commit + git push
byblos-dev sync --import   # git pull --ff-only + import

Stagea SÓLO el .jsonl (nunca barre otros cambios), salta si la memoria no cambió, y el pull es --ff-only (no auto-mergea). --no-push/--no-pull para quedarte con la parte local.

El round-trip es idempotente: cada línea lleva un source estable, así reimportar no duplica. El .jsonl entra como active (es memoria de proyecto ya curada). Reglas:

• Trackeá el .jsonl (commiteable, mergeable). Gitignorá el .db/-wal/-shm (binario, local).
• En equipo, tratá el .jsonl como cualquier archivo: PRs, review, merge por línea.

Conectar el MCP

byblos-dev init ya escribe .mcp.json en el proyecto (modo global: node <server.js global>), así que normalmente no tenés que configurarlo a mano — solo reiniciar el cliente para que lo lea. Si lo armás manual, apuntá al binario byblos-dev-mcp. Variables de entorno:

| Variable | Default | Uso | |---|---|---| | BYBLOS_PROJECT_DB | .byblos/memory.db | memoria del proyecto | | BYBLOS_GLOBAL_DB | ~/.byblos/memory.db | memoria compartida entre proyectos | | BYBLOS_EMBEDDER | (vacío) | p. ej. openai:text-embedding-3-small para búsqueda semántica | | OPENAI_API_KEY | — | requerido si el embedder es OpenAI |

Sin BYBLOS_EMBEDDER, funciona solo con FTS5 (cero dependencias externas).

Tools MCP

memory_search · memory_get · memory_write · memory_supersede · memory_confirm · memory_link · memory_trace · session_start · session_end

Arquitectura

Ver AGENTS.md (decisiones AD-*) y HANDOFF.md (estado y siguientes pasos). El núcleo no depende de SQLite ni de MCP; el almacenamiento pasa por el puerto IMemoryStore.