lampson 0.1.0 → 0.1.1

package/lib/tools/bash.syn

@@ -1,105 +1,105 @@
--- lib/tools/bash.syn — ejecutar un comando de shell con cwd = workspace/
---
--- MIGAS:
---   * en Windows `bash` a secas resuelve al de WSL y cuelga; usar Git Bash explícito (default) o cmd.
---   * NO usar `run()` para el comando del modelo: se cuelga para siempre si el comando deja un
---     descendiente vivo (Windows hereda el pipe de stdout) y su timeout mata solo al hijo directo.
---     Desde 2026-08-27 el comando corre con `proc_spawn` (v0.6.9): eventos por línea hasta el exit o el
---     plazo, stdin cerrado (EOF: nada se queda esperando teclado), y `proc_close` mata el ÁRBOL
---     (Job Object / process group) — un nieto con el pipe abierto no cuelga (1 s de gracia). Adiós
---     bash_wrapper.sh y archivos temporales.
---   * el proceso hijo NO hereda el scope de Synsema (un `cat ../x` en bash funciona). El aislamiento del
---     shell lo dan permission.syn (patrones) + el operador (contenedor si hace falta).
-use "./common.syn" as c
-use "./proc.syn" as proc
-
-export task shell_config()
-    require env("LAMPSON_*")
-    require env("OS")
-    let is_win be env("OS", "") == "Windows_NT"
-    let shell be env("LAMPSON_SHELL", when is_win then "C:\\Program Files\\Git\\bin\\bash.exe" otherwise "bash")
-    let is_cmd be c.ends_with(lower(shell), "cmd.exe") or lower(shell) == "cmd"
-    give {"shell": shell, "flag": env("LAMPSON_SHELL_FLAG", when is_cmd then "/c" otherwise "-c"), "is_cmd": is_cmd}
-
--- comandos que son servidores/watchers: rechazarlos ANTES de correrlos. El timeout mata el árbol, pero
--- un servidor lanzado acá dejó un huérfano con el puerto 3000 tomado y el `process` real se fue al 3001
--- (2026-08-27). La descripción ya lo decía; el modelo lo intentó igual "con | head" — hay que impedirlo.
-let SERVER_RE be ".*((npm|pnpm|yarn|bun)( run)? (dev|start|serve|watch|preview)|npx (next|vite|nodemon|serve|http-server)|next (dev|start)|vite( |$)|nodemon|synsema serve|uvicorn|gunicorn|flask run|manage\\.py runserver|python3? -m http\\.server|rails s(erver)?|php -S|ng serve|cargo (run|watch)|go run|dotnet (run|watch)|tail -f).*"
-
-export task looks_like_server(command)
-    let cmd be trim(lower(replace_text(command, "\n", " ")))
-    when matches(cmd, "timeout [0-9]+.*")
-        give false
-    give matches(cmd, SERVER_RE)
-
--- corre argv con plazo real: junta stdout+stderr por líneas, corta al plazo y mata el árbol
-export task run_capture(exe, argv, t)
-    require exec
-    require time
-    require file("workspace")
-    require file("workspace/*")
-    let p be proc_spawn(exe, argv, {"cwd": c.ROOT, "stderr": "merge", "on_full": "drop_oldest"})
-    proc_close_stdin(p)
-    let deadline be now() + t
-    let lines be []
-    let size be 0
-    let cut be false
-    let code be nothing
-    let timed_out be false
-    while code == nothing and not timed_out
-        let left be deadline - now()
-        when left <= 0
-            set timed_out to true
-        otherwise
-            let ev be proc_recv(p, when left < 0.2 then 0.2 otherwise left)
-            when ev == nothing
-                set timed_out to now() >= deadline
-            otherwise when ev["type"] == "exit"
-                set code to ev["data"]["exit_code"]
-            otherwise when size < 1000000
-                set lines to append(lines, ev["data"])
-                set size to size + length(ev["data"]) + 1
-            otherwise
-                set cut to true
-    proc_close(p)
-    let out be join(lines, "\n")
-    when cut
-        set out to out + "\n[output truncated at 1 MB]"
-    when timed_out
-        give "ERROR: timeout after " + text(t) + "s — the command and its child processes were killed. For servers/watchers use the process tool. Output so far:\n" + out
-    when code != 0
-        set out to out + "\n[exit code " + text(code) + "]"
-    give out
-
-export task tool(command, timeout)
-    require exec
-    require time
-    require env("LAMPSON_*")
-    require env("OS")
-    require file(".lampson")
-    require file(".lampson/*")
-    when looks_like_server(command)
-        give "REFUSED: this looks like a server/watcher (`" + command + "`). bash kills its process tree at the timeout, and a dev server left half-killed keeps its port busy. Use the process tool instead: process(action=\"start\", name=\"dev\", command=\"...\"), then process(action=\"logs\") or just keep working — its new output is appended to every bash result. If it is really a one-shot command, wrap it with `timeout 30 ...` and explain why."
-    let sc be shell_config()
-    let t be when timeout == nothing then 120 otherwise floor(timeout)
-    when t > 600
-        set t to 600
-    when t < 1
-        set t to 1
-    let out be run_capture(sc["shell"], [sc["flag"], command], t)
-    when trim(out) == ""
-        set out to "(no output)"
-    -- lo que pasó mientras tanto en los procesos gestionados (servidores) — el agente "ve la consola"
-    let rep be proc.report()
-    when rep != ""
-        set out to out + "\n\n" + rep
-    give c.truncate(out, c.MAX_OUTPUT)
-
-export let SPEC be {
-    "name": "bash",
-    "description": "Run a shell command with the workspace root as working directory (no persistent shell state between calls: cwd and env reset). Returns stdout+stderr and [exit code N] when non-zero. Use it for git, tests, builds, package managers. Commands are killed (with their child processes) after the timeout (default 120s, max 600) — so NEVER run a server, watcher or REPL here: use the `process` tool (start/logs/stop) for anything long-running; its new log lines are appended to every bash result automatically. Avoid interactive commands. Prefer read/grep/find over cat/grep/find for files.",
-    "parameters": {"type": "object", "properties": {
-        "command": {"type": "string"},
-        "timeout": {"type": "integer", "description": "Seconds (optional, default 120, max 600)"}
-    }, "required": ["command"]}
-}
+-- lib/tools/bash.syn — ejecutar un comando de shell con cwd = workspace/
+--
+-- MIGAS:
+--   * en Windows `bash` a secas resuelve al de WSL y cuelga; usar Git Bash explícito (default) o cmd.
+--   * NO usar `run()` para el comando del modelo: se cuelga para siempre si el comando deja un
+--     descendiente vivo (Windows hereda el pipe de stdout) y su timeout mata solo al hijo directo.
+--     Desde 2026-08-27 el comando corre con `proc_spawn` (v0.6.9): eventos por línea hasta el exit o el
+--     plazo, stdin cerrado (EOF: nada se queda esperando teclado), y `proc_close` mata el ÁRBOL
+--     (Job Object / process group) — un nieto con el pipe abierto no cuelga (1 s de gracia). Adiós
+--     bash_wrapper.sh y archivos temporales.
+--   * el proceso hijo NO hereda el scope de Synsema (un `cat ../x` en bash funciona). El aislamiento del
+--     shell lo dan permission.syn (patrones) + el operador (contenedor si hace falta).
+use "./common.syn" as c
+use "./proc.syn" as proc
+
+export task shell_config()
+    require env("LAMPSON_*")
+    require env("OS")
+    let is_win be env("OS", "") == "Windows_NT"
+    let shell be env("LAMPSON_SHELL", when is_win then "C:\\Program Files\\Git\\bin\\bash.exe" otherwise "bash")
+    let is_cmd be c.ends_with(lower(shell), "cmd.exe") or lower(shell) == "cmd"
+    give {"shell": shell, "flag": env("LAMPSON_SHELL_FLAG", when is_cmd then "/c" otherwise "-c"), "is_cmd": is_cmd}
+
+-- comandos que son servidores/watchers: rechazarlos ANTES de correrlos. El timeout mata el árbol, pero
+-- un servidor lanzado acá dejó un huérfano con el puerto 3000 tomado y el `process` real se fue al 3001
+-- (2026-08-27). La descripción ya lo decía; el modelo lo intentó igual "con | head" — hay que impedirlo.
+let SERVER_RE be ".*((npm|pnpm|yarn|bun)( run)? (dev|start|serve|watch|preview)|npx (next|vite|nodemon|serve|http-server)|next (dev|start)|vite( |$)|nodemon|synsema serve|uvicorn|gunicorn|flask run|manage\\.py runserver|python3? -m http\\.server|rails s(erver)?|php -S|ng serve|cargo (run|watch)|go run|dotnet (run|watch)|tail -f).*"
+
+export task looks_like_server(command)
+    let cmd be trim(lower(replace_text(command, "\n", " ")))
+    when matches(cmd, "timeout [0-9]+.*")
+        give false
+    give matches(cmd, SERVER_RE)
+
+-- corre argv con plazo real: junta stdout+stderr por líneas, corta al plazo y mata el árbol
+export task run_capture(exe, argv, t)
+    require exec
+    require time
+    require file("workspace")
+    require file("workspace/*")
+    let p be proc_spawn(exe, argv, {"cwd": c.ROOT, "stderr": "merge", "on_full": "drop_oldest"})
+    proc_close_stdin(p)
+    let deadline be now() + t
+    let lines be []
+    let size be 0
+    let cut be false
+    let code be nothing
+    let timed_out be false
+    while code == nothing and not timed_out
+        let left be deadline - now()
+        when left <= 0
+            set timed_out to true
+        otherwise
+            let ev be proc_recv(p, when left < 0.2 then 0.2 otherwise left)
+            when ev == nothing
+                set timed_out to now() >= deadline
+            otherwise when ev["type"] == "exit"
+                set code to ev["data"]["exit_code"]
+            otherwise when size < 1000000
+                set lines to append(lines, ev["data"])
+                set size to size + length(ev["data"]) + 1
+            otherwise
+                set cut to true
+    proc_close(p)
+    let out be join(lines, "\n")
+    when cut
+        set out to out + "\n[output truncated at 1 MB]"
+    when timed_out
+        give "ERROR: timeout after " + text(t) + "s — the command and its child processes were killed. For servers/watchers use the process tool. Output so far:\n" + out
+    when code != 0
+        set out to out + "\n[exit code " + text(code) + "]"
+    give out
+
+export task tool(command, timeout)
+    require exec
+    require time
+    require env("LAMPSON_*")
+    require env("OS")
+    require file(".lampson")
+    require file(".lampson/*")
+    when looks_like_server(command)
+        give "REFUSED: this looks like a server/watcher (`" + command + "`). bash kills its process tree at the timeout, and a dev server left half-killed keeps its port busy. Use the process tool instead: process(action=\"start\", name=\"dev\", command=\"...\"), then process(action=\"logs\") or just keep working — its new output is appended to every bash result. If it is really a one-shot command, wrap it with `timeout 30 ...` and explain why."
+    let sc be shell_config()
+    let t be when timeout == nothing then 120 otherwise floor(timeout)
+    when t > 600
+        set t to 600
+    when t < 1
+        set t to 1
+    let out be run_capture(sc["shell"], [sc["flag"], command], t)
+    when trim(out) == ""
+        set out to "(no output)"
+    -- lo que pasó mientras tanto en los procesos gestionados (servidores) — el agente "ve la consola"
+    let rep be proc.report()
+    when rep != ""
+        set out to out + "\n\n" + rep
+    give c.truncate(out, c.MAX_OUTPUT)
+
+export let SPEC be {
+    "name": "bash",
+    "description": "Run a shell command with the workspace root as working directory (no persistent shell state between calls: cwd and env reset). Returns stdout+stderr and [exit code N] when non-zero. Use it for git, tests, builds, package managers. Commands are killed (with their child processes) after the timeout (default 120s, max 600) — so NEVER run a server, watcher or REPL here: use the `process` tool (start/logs/stop) for anything long-running; its new log lines are appended to every bash result automatically. Avoid interactive commands. Prefer read/grep/find over cat/grep/find for files.",
+    "parameters": {"type": "object", "properties": {
+        "command": {"type": "string"},
+        "timeout": {"type": "integer", "description": "Seconds (optional, default 120, max 600)"}
+    }, "required": ["command"]}
+}

package/lib/tools/edit.syn

@@ -1,32 +1,32 @@
--- lib/tools/edit.syn — reemplazo exacto y único (sin fuzzy replacers: exactitud antes que magia)
-use "./common.syn" as c
-
-export task tool(path, old_string, new_string, replace_all)
-    require file("workspace")
-    require file("workspace/*")
-    let real be c.ws(path)
-    let shown be c.unws(real)
-    c.check_observed(real, "edit")
-    let content be read_file(real)
-    let parts be split(content, old_string)
-    let n be length(parts) - 1
-    when n == 0
-        raise("old_string not found in " + shown + " — read the file and copy the exact text (whitespace included)")
-    let all be when replace_all == nothing then false otherwise replace_all
-    when n > 1
-        when not all
-            raise(`old_string appears {text(n)} times in {shown}; include more surrounding context to make it unique, or pass replace_all=true`)
-    write_file(real, join(parts, new_string))
-    c.mark_observed(real)
-    give `edited {shown}: {text(n)} replacement(s)`
-
-export let SPEC be {
-    "name": "edit",
-    "description": "Replace an exact string in a file. old_string must match EXACTLY (including whitespace and indentation) and be unique in the file, otherwise the call fails — include more surrounding lines to disambiguate, or set replace_all=true to replace every occurrence. The file MUST have been read in this session (and not changed since), or the call is rejected.",
-    "parameters": {"type": "object", "properties": {
-        "path": {"type": "string"},
-        "old_string": {"type": "string"},
-        "new_string": {"type": "string"},
-        "replace_all": {"type": "boolean"}
-    }, "required": ["path", "old_string", "new_string"]}
-}
+-- lib/tools/edit.syn — reemplazo exacto y único (sin fuzzy replacers: exactitud antes que magia)
+use "./common.syn" as c
+
+export task tool(path, old_string, new_string, replace_all)
+    require file("workspace")
+    require file("workspace/*")
+    let real be c.ws(path)
+    let shown be c.unws(real)
+    c.check_observed(real, "edit")
+    let content be read_file(real)
+    let parts be split(content, old_string)
+    let n be length(parts) - 1
+    when n == 0
+        raise("old_string not found in " + shown + " — read the file and copy the exact text (whitespace included)")
+    let all be when replace_all == nothing then false otherwise replace_all
+    when n > 1
+        when not all
+            raise(`old_string appears {text(n)} times in {shown}; include more surrounding context to make it unique, or pass replace_all=true`)
+    write_file(real, join(parts, new_string))
+    c.mark_observed(real)
+    give `edited {shown}: {text(n)} replacement(s)`
+
+export let SPEC be {
+    "name": "edit",
+    "description": "Replace an exact string in a file. old_string must match EXACTLY (including whitespace and indentation) and be unique in the file, otherwise the call fails — include more surrounding lines to disambiguate, or set replace_all=true to replace every occurrence. The file MUST have been read in this session (and not changed since), or the call is rejected.",
+    "parameters": {"type": "object", "properties": {
+        "path": {"type": "string"},
+        "old_string": {"type": "string"},
+        "new_string": {"type": "string"},
+        "replace_all": {"type": "boolean"}
+    }, "required": ["path", "old_string", "new_string"]}
+}

package/lib/tools/memo.syn

@@ -1,148 +1,148 @@
--- lib/tools/memo.syn — memoria por proyecto: notas Markdown que el agente escribe y relee
---
--- Dónde: lampson/memory/<slug>/<nombre>.md — <slug> sale de la ruta REAL del workspace
--- (LAMPSON_WORKSPACE, que fija el launcher): "<carpeta>-<hash8>". Así cada proyecto tiene su carpeta
--- aunque dos se llamen igual, y las notas viven en lampson (no ensucian el repo del usuario).
---
--- El system prompt lleva SOLO el índice (nombre + primera línea de cada nota); el contenido entra al
--- contexto cuando el agente llama `memory(read)`. Son archivos: el humano los lee/edita a mano y la
--- UI web los muestra.
-use "./common.syn" as c
-
-export let ROOT be "memory"
-
-task valid_name(name)
-    when name == nothing or name == ""
-        give false
-    give matches(name, "[a-zA-Z0-9_-]{1,60}")
-
--- slug del proyecto montado
-export task slug()
-    require env("LAMPSON_*")
-    let ws be env("LAMPSON_WORKSPACE", "workspace")
-    let norm be replace_text(lower(ws), "\\", "/")
-    let parts be where(split(norm, "/"), (x) => x != "")
-    let base be when length(parts) > 0 then parts[length(parts) - 1] otherwise "workspace"
-    let runs be find_all(base, "[a-z0-9]+")
-    let clean be when length(runs) == 0 then "project" otherwise join(runs, "-")
-    let h be slice(decode(sha256(norm), "hex"), 0, 8)
-    give clean + "-" + h
-
-export task dir()
-    require env("LAMPSON_*")
-    give ROOT + "/" + slug()
-
-task path(name)
-    give dir() + "/" + name + ".md"
-
--- [{name, title}] — title = primera línea no vacía (sin '#')
-export task list()
-    require env("LAMPSON_*")
-    require file.read("memory")
-    require file.read("memory/*")
-    let out be []
-    try
-        each e in list_dir(dir())
-            when not e["is_dir"] and c.ends_with(e["name"], ".md")
-                let name be slice(e["name"], 0, length(e["name"]) - 3)
-                let title be ""
-                each line in split(read_file(path(name)), "\n")
-                    when title == "" and trim(line) != ""
-                        set title to trim(replace_text(line, "#", ""))
-                set out to append(out, {"name": name, "title": when length(title) > 120 then slice(title, 0, 120) otherwise title})
-    recover err
-        -- el runtime lanza "Not a directory: …" (mayúscula) cuando memory/<slug> aún no existe
-        let e be lower(text(err))
-        when not contains(e, "not a directory") and not contains(e, "not found") and not contains(e, "no such")
-            raise(err)
-        give []
-    give sort_by(out, (x) => x["name"])
-
-export task note_read(name)
-    require env("LAMPSON_*")
-    require file.read("memory")
-    require file.read("memory/*")
-    when not valid_name(name)
-        raise("invalid note name")
-    try
-        give read_file(path(name))
-    recover err
-        raise("no such note '" + name + "'. Existing: " + join(apply((x) => x["name"], list()), ", "))
-
-export task note_write(name, content)
-    require env("LAMPSON_*")
-    require file("memory")
-    require file("memory/*")
-    when not valid_name(name)
-        raise("invalid note name '" + text(name) + "' (letters, digits, - or _)")
-    write_file(path(name), content)
-    give "saved memory/" + slug() + "/" + name + ".md (" + text(length(content)) + " chars)"
-
-export task note_append(name, content)
-    require env("LAMPSON_*")
-    require file("memory")
-    require file("memory/*")
-    when not valid_name(name)
-        raise("invalid note name")
-    let prev be ""
-    try
-        set prev to read_file(path(name))
-    recover err
-        set prev to ""
-    let joined be when prev == "" then content otherwise prev + "\n\n" + content
-    write_file(path(name), joined)
-    give "appended to " + name + ".md (" + text(length(joined)) + " chars total)"
-
-export task note_clear(name)
-    require env("LAMPSON_*")
-    require file("memory")
-    require file("memory/*")
-    when not valid_name(name)
-        raise("invalid note name")
-    write_file(path(name), "")
-    give "cleared " + name + ".md (the file stays empty; the user can delete it)"
-
--- sección del system prompt
-export task prompt_section()
-    require env("LAMPSON_*")
-    require file.read("memory")
-    require file.read("memory/*")
-    let items be list()
-    let head be "\n\n# Project memory (your own notes about THIS project, in memory/" + slug() + "/ — read with memory(read), keep them current with memory(write|append))"
-    when length(items) == 0
-        give head + "\n(empty — when you discover something non-obvious about this project: how to run/test it, gotchas, decisions, where things live — save it with memory(write). Keep notes short and factual.)"
-    let lines be [head]
-    each it in items
-        set lines to append(lines, "- " + it["name"] + ": " + it["title"])
-    give join(lines, "\n")
-
--- ---------- tool ----------
-
-export task tool(action, name, content)
-    require env("LAMPSON_*")
-    require file("memory")
-    require file("memory/*")
-    when action == "list"
-        let items be list()
-        when length(items) == 0
-            give "no notes yet for this project"
-        give join(apply((x) => x["name"] + ": " + x["title"], items), "\n")
-    when action == "read"
-        give note_read(name)
-    when action == "write"
-        give note_write(name, content)
-    when action == "append"
-        give note_append(name, content)
-    when action == "delete"
-        give note_clear(name)
-    raise("unknown action '" + text(action) + "' (list | read | write | append | delete)")
-
-export let SPEC be {
-    "name": "memory",
-    "description": "Your persistent notes about THIS project, kept across sessions (Markdown files in Lampson's memory folder, never inside the repo). Use `write` to save non-obvious facts you discovered and will need again: how to run/build/test, environment quirks, architecture decisions, where things live, bugs and their causes, what the user prefers. `append` adds to an existing note, `read` loads one, `list` shows them, `delete` clears one. The system prompt shows the index of notes — read the relevant ones before repeating an investigation. Keep notes short, factual and current: update a note instead of writing a contradictory one.",
-    "parameters": {"type": "object", "properties": {
-        "action": {"type": "string", "enum": ["list", "read", "write", "append", "delete"]},
-        "name": {"type": "string", "description": "Note id: letters, digits, - or _ (e.g. how-to-run, db-schema, gotchas)"},
-        "content": {"type": "string", "description": "write/append: Markdown content (first line = title)"}
-    }, "required": ["action"]}
-}
+-- lib/tools/memo.syn — memoria por proyecto: notas Markdown que el agente escribe y relee
+--
+-- Dónde: lampson/memory/<slug>/<nombre>.md — <slug> sale de la ruta REAL del workspace
+-- (LAMPSON_WORKSPACE, que fija el launcher): "<carpeta>-<hash8>". Así cada proyecto tiene su carpeta
+-- aunque dos se llamen igual, y las notas viven en lampson (no ensucian el repo del usuario).
+--
+-- El system prompt lleva SOLO el índice (nombre + primera línea de cada nota); el contenido entra al
+-- contexto cuando el agente llama `memory(read)`. Son archivos: el humano los lee/edita a mano y la
+-- UI web los muestra.
+use "./common.syn" as c
+
+export let ROOT be "memory"
+
+task valid_name(name)
+    when name == nothing or name == ""
+        give false
+    give matches(name, "[a-zA-Z0-9_-]{1,60}")
+
+-- slug del proyecto montado
+export task slug()
+    require env("LAMPSON_*")
+    let ws be env("LAMPSON_WORKSPACE", "workspace")
+    let norm be replace_text(lower(ws), "\\", "/")
+    let parts be where(split(norm, "/"), (x) => x != "")
+    let base be when length(parts) > 0 then parts[length(parts) - 1] otherwise "workspace"
+    let runs be find_all(base, "[a-z0-9]+")
+    let clean be when length(runs) == 0 then "project" otherwise join(runs, "-")
+    let h be slice(decode(sha256(norm), "hex"), 0, 8)
+    give clean + "-" + h
+
+export task dir()
+    require env("LAMPSON_*")
+    give ROOT + "/" + slug()
+
+task path(name)
+    give dir() + "/" + name + ".md"
+
+-- [{name, title}] — title = primera línea no vacía (sin '#')
+export task list()
+    require env("LAMPSON_*")
+    require file.read("memory")
+    require file.read("memory/*")
+    let out be []
+    try
+        each e in list_dir(dir())
+            when not e["is_dir"] and c.ends_with(e["name"], ".md")
+                let name be slice(e["name"], 0, length(e["name"]) - 3)
+                let title be ""
+                each line in split(read_file(path(name)), "\n")
+                    when title == "" and trim(line) != ""
+                        set title to trim(replace_text(line, "#", ""))
+                set out to append(out, {"name": name, "title": when length(title) > 120 then slice(title, 0, 120) otherwise title})
+    recover err
+        -- el runtime lanza "Not a directory: …" (mayúscula) cuando memory/<slug> aún no existe
+        let e be lower(text(err))
+        when not contains(e, "not a directory") and not contains(e, "not found") and not contains(e, "no such")
+            raise(err)
+        give []
+    give sort_by(out, (x) => x["name"])
+
+export task note_read(name)
+    require env("LAMPSON_*")
+    require file.read("memory")
+    require file.read("memory/*")
+    when not valid_name(name)
+        raise("invalid note name")
+    try
+        give read_file(path(name))
+    recover err
+        raise("no such note '" + name + "'. Existing: " + join(apply((x) => x["name"], list()), ", "))
+
+export task note_write(name, content)
+    require env("LAMPSON_*")
+    require file("memory")
+    require file("memory/*")
+    when not valid_name(name)
+        raise("invalid note name '" + text(name) + "' (letters, digits, - or _)")
+    write_file(path(name), content)
+    give "saved memory/" + slug() + "/" + name + ".md (" + text(length(content)) + " chars)"
+
+export task note_append(name, content)
+    require env("LAMPSON_*")
+    require file("memory")
+    require file("memory/*")
+    when not valid_name(name)
+        raise("invalid note name")
+    let prev be ""
+    try
+        set prev to read_file(path(name))
+    recover err
+        set prev to ""
+    let joined be when prev == "" then content otherwise prev + "\n\n" + content
+    write_file(path(name), joined)
+    give "appended to " + name + ".md (" + text(length(joined)) + " chars total)"
+
+export task note_clear(name)
+    require env("LAMPSON_*")
+    require file("memory")
+    require file("memory/*")
+    when not valid_name(name)
+        raise("invalid note name")
+    write_file(path(name), "")
+    give "cleared " + name + ".md (the file stays empty; the user can delete it)"
+
+-- sección del system prompt
+export task prompt_section()
+    require env("LAMPSON_*")
+    require file.read("memory")
+    require file.read("memory/*")
+    let items be list()
+    let head be "\n\n# Project memory (your own notes about THIS project, in memory/" + slug() + "/ — read with memory(read), keep them current with memory(write|append))"
+    when length(items) == 0
+        give head + "\n(empty — when you discover something non-obvious about this project: how to run/test it, gotchas, decisions, where things live — save it with memory(write). Keep notes short and factual.)"
+    let lines be [head]
+    each it in items
+        set lines to append(lines, "- " + it["name"] + ": " + it["title"])
+    give join(lines, "\n")
+
+-- ---------- tool ----------
+
+export task tool(action, name, content)
+    require env("LAMPSON_*")
+    require file("memory")
+    require file("memory/*")
+    when action == "list"
+        let items be list()
+        when length(items) == 0
+            give "no notes yet for this project"
+        give join(apply((x) => x["name"] + ": " + x["title"], items), "\n")
+    when action == "read"
+        give note_read(name)
+    when action == "write"
+        give note_write(name, content)
+    when action == "append"
+        give note_append(name, content)
+    when action == "delete"
+        give note_clear(name)
+    raise("unknown action '" + text(action) + "' (list | read | write | append | delete)")
+
+export let SPEC be {
+    "name": "memory",
+    "description": "Your persistent notes about THIS project, kept across sessions (Markdown files in Lampson's memory folder, never inside the repo). Use `write` to save non-obvious facts you discovered and will need again: how to run/build/test, environment quirks, architecture decisions, where things live, bugs and their causes, what the user prefers. `append` adds to an existing note, `read` loads one, `list` shows them, `delete` clears one. The system prompt shows the index of notes — read the relevant ones before repeating an investigation. Keep notes short, factual and current: update a note instead of writing a contradictory one.",
+    "parameters": {"type": "object", "properties": {
+        "action": {"type": "string", "enum": ["list", "read", "write", "append", "delete"]},
+        "name": {"type": "string", "description": "Note id: letters, digits, - or _ (e.g. how-to-run, db-schema, gotchas)"},
+        "content": {"type": "string", "description": "write/append: Markdown content (first line = title)"}
+    }, "required": ["action"]}
+}