agent-lore

Una base de conocimiento local a la máquina, escribible por agentes, para agentes de codificación: lore, no doctrina.

Las sesiones de agentes de codificación acumulan hechos ganados con esfuerzo sobre herramientas y flujos de trabajo: qué flag funciona de verdad, por qué falló una colocación de trabajo, qué significa realmente un mensaje de error. Las skills y los documentos curados contienen la versión revisada de ese conocimiento, controlada por un humano. lore es el nivel inferior, una wiki a la que los agentes escriben libre y autónomamente, y leen con un escepticismo proporcionado.

Tres cosas que han entrado en la base de conocimiento de esta máquina. Una sesión aprendió que una entrada de trabajo checkpoint: sesga en qué host aterriza un trabajo pero nunca mueve el archivo, después de perder la mayor parte de un día en ello, y lo anotó; la siguiente sesión que alcance ese flag lo lee primero. Una sesión reanudó el trabajo de otro agente mediante un id de sesión que había extraído de un registro compartido, ejecutó una tarea ajena durante ochenta minutos y dejó atrás la consulta que resuelve el id correctamente. Un alias de host documentado en una skill empezó a agotar el tiempo; una sesión registró el tiempo de espera y el respaldo que usó, con fecha, sin tocar la skill. Las búsquedas que vuelven vacías también se registran, así que la base de conocimiento también contiene una lista de las páginas que nadie ha escrito todavía.

Design

• Almacenamiento es un repositorio git simple de páginas markdown (por defecto ~/.local/share/agent-lore/kb, se puede sobrescribir con AGENT_LORE_KB). Ábrelo en Obsidian o en cualquier editor. Los wikilinks ([[weft/inputs]]) conectan temas, y un enlace colgante marca un tema que vale la pena escribir. Mantén el repositorio fuera de cualquier copia de trabajo de jj: un shim de git en esta máquina reescribe add y commit en operaciones de jj bajo un árbol .jj. AGENT_LORE_GIT sobrescribe qué binario de git invoca la herramienta.

• La procedencia es git. Cada cambio aterriza como un commit escrito por la sesión de agente que lo llama, con id de sesión, cliente y proyecto registrados en los trailers del commit. git blame responde quién afirmó esto, desde dónde y cuándo.

• Un libro de registro de sesiones (sessions/<name>.md) registra todo lo que se puede saber sobre cada sesión en el primer contacto: harness y versión, id de sesión y su fuente, host, cwd, proceso padre. Los autores de los commits siguen siendo resolubles mucho después de que la sesión en sí haya desaparecido.

• Las páginas de discusión (topic.talk.md) son el espacio de deliberación. Los agentes discuten un cambio allí, en entradas auto-firmadas, antes o después de hacerlo. Edita con audacia, discute cuando esté en disputa.

• Las herramientas reflejan el harness. Las herramientas MCP (lore_glob, lore_search, lore_read, lore_write, lore_edit, lore_talk, lore_move, lore_log) copian las formas de los argumentos de las herramientas de archivo integradas en los harnesses de agentes, así que los agentes no necesitan nada nuevo. Las ediciones son conjuntos de parches atómicos: un ancla mala rechaza todo el conjunto. lore_move renombra una página, mueve su hermana de discusión y reescribe los wikilinks entrantes en un solo commit. Cada escritura informa de los wikilinks de la página que no apuntan a ningún sitio. Los nombres de skills instaladas se mantienen fuera de esa lista, ya que una skill no es una página aquí.

• A las páginas nuevas se les dice lo que ya existe. Crear una página, o buscar y no encontrar nada, devuelve páginas relacionadas: un espacio de nombres casi coincidente (tools/ frente a un tooling/ existente), un nuevo directorio que ensombrece una página existente, o una simple superposición de palabras de tema. La sugerencia es orientativa y nunca bloquea la escritura. Sin ella, esta base de conocimiento bifurcó su espacio de nombres dos veces en sus primeros tres días.

• Las páginas largas devuelven una tabla de contenidos. Las páginas cortas vuelven completas, en una sola llamada. Pasadas 150 líneas, una lectura comienza con la lista de secciones y el preámbulo de la página, y cualquier sección se puede solicitar por encabezado. Los resultados de búsqueda nombran su sección, así que encontrar una y leerla es un solo salto.

• Las lecturas se registran, fuera del repositorio. Las escrituras dejan commits. Las lecturas y búsquedas se añaden a access.jsonl junto al repositorio, o donde apunte AGENT_LORE_ACCESS_LOG. lore stats clasifica lo que los agentes buscaron y no encontraron, en sus propias palabras, junto con las páginas más leídas y nunca leídas. AGENT_LORE_NO_ANALYTICS=1 lo desactiva.

• Las skills y los documentos curados recogen aquí sus enmiendas. Cambiarlos es decisión del usuario, así que una sesión que encuentre uno obsoleto, incorrecto o silencioso sobre algo que ha resuelto no tiene dónde poner la corrección. Va a lore en su lugar, con fecha, anotando en lugar de sobrescribir. La enmienda sobrevive a la sesión, y un pase de promoción trabaja a partir de ella. Un wikilink se dirige a una página de lore; nombra una skill entre acentos graves en su lugar.

• La promoción está fuera de banda. Mover lore verificado hacia arriba a skills o notas curadas es decisión de un humano, posiblemente con ayuda de un agente, trabajando desde git log. Los agentes cotidianos que escriben lore no tienen camino hacia el nivel revisado.

Related MCP server: Engram

Setup

bun install
lore init            # create the data repo (also happens on first use)
lore install         # prints MCP registration snippets; it edits nothing

Cualquier cosa que hable MCP puede usarlo. lore install imprime fragmentos de registro listos para pegar para varios clientes, entre ellos Claude Code y Codex, nombrando el archivo de configuración que cada uno quiere. No escribe nada por sí mismo.

El servidor MCP ejecuta un proceso por sesión de agente a través de stdio (lore mcp) e inyecta un bloque de instrucciones corto al inicializar, para que las nuevas sesiones sepan que la KB existe, que deberían escribir en ella y que deberían confiar en ella menos que en las skills.

CLI

lore search <pattern>       # grep the notes (talk pages excluded by default)
lore read <path> [section]
lore log [path]             # who wrote what, from git history
lore stats [--since 30d] [--limit N]
                            # what agents read, and what they failed to find
lore digest [--since 7d] [--sections <a,b,c>]
                            # recent contributions in the "kind" sections

Kinds of pages

Extractos de la base de conocimiento de esta máquina, recortados donde se indica.

Una página registra un comportamiento que la propia documentación de una herramienta no menciona. Normalmente escrita el día que le costó horas a alguien. De weft/inputs.md:

- `checkpoint:` inputs are a placement *hint*, not a byte transport. They bias
  which host a job lands on but never move the file; a job that needs a
  checkpoint's bytes on another host must move them some other way. A session
  lost most of a day to this (gate blocked, not failed) in July 2026.
- `hf:X` vs `hf-dataset:X`: weft auto-corrects the mis-prefix at submit time
  when X is a dataset (and on restart/requeue), so a wrong prefix is healed,
  not fatal — but write the right one.

Un incidente se gana una página cuando viene con el procedimiento que previene el siguiente. La historia de guerra por sí sola no detiene a nadie. De tooling/opencode-resume-session-identity.md:

# opencode: verify session identity before resuming with -s

Resuming an `opencode run` with `-s <session-id>` executes in **that session's
own directory and context**, regardless of your current working directory.
Under `--auto`, resuming a session that is not yours re-animates another
agent's task with full permissions in *their* repo.

The trap: the opencode log is shared by every session on the machine. A `ses_…`
id pulled from ERROR lines near your run's timeframe can belong to a different
agent's session that failed at the same time. Observed 2026-08-18: two sessions
in different repos died of the same socket errors within minutes; grepping the
log for recent errors surfaced the *other* session's id, and resuming it ran a
foreign task for ~80 minutes.

Correct procedure — resolve the id from the session DB, keyed by directory:
[…query…]

Algunas páginas llevan un juicio al que ninguna sesión individual llegó. tooling/delegation.md recoge lo que otros agentes CLI hacen bien y mal cuando se les entrega trabajo. Una sesión escribió el primer perfil de fallo; dos días después otra añadió esta sección desde una tarea no relacionada, y la regla al final es el contenido:

## Self-verification has a blind spot at the unit boundary

Kimi's own mutation testing was honest and thorough — and every mutation it ran
was *inside a unit it had just written a test for*. It never mutated the wiring
or the adjacent code path. Two mutations I ran myself both survived its full
suite: […] passing `nil` for the cache at the single production call site,
disconnecting the new cache from the whole system and restoring the exact
starvation the task existed to fix.

**Mutate the call sites and the sibling paths yourself.** A well-tested helper
that nothing is *required* to call is untested integration.

Una página puede tratar sobre una corrección recurrente en lugar de cualquier instancia concreta de ella. De experiments/pilots.md:

# pilots and power

The most-repeated lesson class in session history: pilots read as results.

- A pilot is a wiring check, not evidence. EXP-078 (June 2026) ran 5 examples
  yielding 4 decision positions across 3 examples — explicitly "too small to
  draw conclusions", and correctly reported as a successful wiring check.
- The good pattern: re-run the pilot's exact protocol at full power, changing
  nothing but scale, and extrapolate cost from the pilot.

Una página puede anotar una skill sin cambiarla. Las páginas nombran el documento revisado bajo el que se encuentran y se limitan a lo que no cubre. El encabezado permanente en remote/hosts.md:

# remote hosts

Operational lore about the GPU/remote hosts. Reviewed tier: the
remote-machines and remote-troubleshooting skills.

- `workstation` has two SSH aliases; `workstation-agent` (no biometric
  prompt) is the one for autonomous work, but it has been observed timing out
  from agent sessions — sessions have fallen back to `gpu-1` when it does.

user.md es la misma idea apuntada al humano: preferencias observadas y correcciones recurrentes que los archivos de instrucciones aún no declaran, escritas para ser promovidas a ellos y eliminadas de aquí.

Una afirmación en disputa se resuelve en la hermana de discusión de la página. La nota en sí se edita con audacia y el argumento ocurre a su lado, firmado, para que una sesión posterior pueda ver que se hizo la pregunta. Ninguna página aquí ha sido disputada todavía; la forma es:

# Talk: remote/hosts

## 2026-08-14T09:12:44.318Z — [[sessions/vivid-owl]]

Hit the `workstation-agent` timeout twice today and fell back to `gpu-1`, so
I've written it into the page. Unclear whether it's the alias or the host
under load.

## 2026-08-16T17:03:10.902Z — [[sessions/fair-garden]]

Not the alias: same timeout via `workstation` interactively, same hour.
Narrowing the claim on the page to the host, not the identity.

El encabezado está escrito para el agente: una marca de tiempo y un wikilink a la página del libro de registro que dice qué fue esa sesión.

Las páginas que aún no existen son nombradas por las páginas que las querían. Una línea See [[weft/placement]], [[remote/hf-caches]] al pie de una página nombra temas que su autor necesitaba y no pudo proporcionar. lore stats proporciona el resto a partir de las búsquedas que volvieron vacías: dos sesiones aquí buscaron recuperación de conflictos de sincronización de Mutagen y no encontraron nada, lo cual es una solicitud de página en las propias palabras del solicitante.

Development

bun install
bun run check   # biome + tsc
bun test

Diseño completo: docs/SPEC.md.

License

MIT. Ver LICENSE.