LWC

LWC — Memoria Proactiva para Agentes de IA

Impulsado por agentes · Persistente · Basado en fuentes

English · 简体中文 · 日本語 · Español · Português (Brasil) · Français · Русский

lwc es una CLI de memoria proactiva impulsada por agentes para agentes de IA. Permite que los agentes recuperen, mantengan y evolucionen de forma autónoma conocimiento persistente y basado en fuentes a lo largo de las sesiones.

Funciona con Claude Code, Codex, Cursor, OpenCode, Gemini CLI, Kiro, Hermes, Antigravity y pi.

LWC convierte documentos seleccionados en una Wiki duradera. Los agentes razonan y sintetizan; lwc preserva fuentes, páginas, citas, enlaces, índices e historial para que el conocimiento se acumule en lugar de redescubrirse a partir de fragmentos crudos en cada consulta.

LWC es Memoria de Agente, no RAG

Tanto RAG como LWC pueden ayudar a un LLM a trabajar con documentos externos, pero mantienen el estado en lugares diferentes. Una solicitud RAG típica recupera fragmentos crudos y construye una respuesta en el momento de la consulta:

query -> retrieve chunks -> generate answer

LWC conserva el trabajo útil entre solicitudes:

task -> recall maintained Wiki -> reason from sources and prior synthesis
     -> write durable improvements back

La recuperación es una operación dentro de LWC, no su principio organizador. El artefacto duradero es una Wiki basada en fuentes cuyas páginas, citas, enlaces, contradicciones e historial se revisan a medida que cambia el conocimiento. Por lo tanto, LWC no requiere incrustaciones ni una base de datos vectorial, y no descarta cada síntesis después de responder. Puede complementar a RAG, pero no es RAG en tiempo de consulta.

El Agente opera LWC

lwc es una interfaz de máquina para Agentes, no una aplicación de toma de notas orientada a humanos. En uso normal, un humano selecciona fuentes, establece objetivos, hace preguntas y revisa respuestas o el Markdown proyectado. El Agente ejecuta la CLI, gestiona el alcance, integra fuentes, mantiene citas y enlaces, y decide qué vale la pena recuperar o escribir de vuelta.

No conduzcas manualmente el flujo de trabajo rutinario de lwc a menos que estés desarrollando o depurando la herramienta. Pide a tu Agente que active la Skill canónica incluida using-lwc en su lugar—generalmente como $using-lwc.

Recomendado: Pide a tu Agente que Configure LWC

Pega este prompt en el Agente que uses. Instala la CLI global, delega toda la configuración de hosts compatibles al instalador idempotente AgentTarget de LWC, y usa la autoconfiguración nativa solo para un Agente no registrado.

Configure LWC completely for this user. Perform and verify the work; do not
merely describe commands for me to run.

Source of truth:
- https://github.com/JanYork/llm-wiki-cli
- https://github.com/JanYork/llm-wiki-cli/tree/main/skills/using-lwc

Requirements:
1. Read this README, `SECURITY.md`, and `skills/using-lwc/SKILL.md`. Install the
   official checksum-verified release if `lwc` is not globally callable; never
   prefix routine commands with a private binary path or `LWC_PROJECT_ROOT`.
2. Run `lwc --version`, initialize global memory once with
   `lwc --scope global init` when missing, then run `lwc agent install --yes`.
   This command detects installed supported Agents and safely installs their
   MCP, Skill, Hook and Instructions using official locations. Do not recreate
   that logic manually or install a native package for the same Agent as well.
3. Inspect `lwc agent status --target all --location global`. Restart affected
   Agents and complete their normal Hook trust review where required. Do not
   initialize a project Wiki or either graph without explicit project consent.
4. If the current runtime is not one of LWC's registered AgentTargets, use its
   official user-level conventions to install the canonical `using-lwc` Skill,
   an additive instruction block, `lwc serve --mcp`, and a bounded session Hook
   only where those surfaces are officially supported. Preserve existing
   configuration, remain idempotent, and report unsupported surfaces instead of
   inventing paths or keys.

Finish with the LWC version, detected and configured Targets, status results,
files changed, unsupported surfaces, and any restart or trust action remaining.

Origen y Agradecimientos

lwc implementa el patrón LLM Wiki propuesto por Andrej Karpathy: un LLM construye y mantiene incrementalmente una Wiki persistente e interconectada en lugar de reconstruir conocimiento a partir de documentos crudos para cada consulta. La arquitectura CLI y ciertos detalles de implementación también se inspiran en nashsu/llm_wiki.

Este proyecto adapta esas ideas a una CLI de Rust priorizando al agente, respaldada por SQLite.

Diseño Principal

El modelo de conocimiento persistente tiene tres capas lógicas:

SQLite es canónico. El árbol de Markdown es una proyección reconstruible para personas y herramientas como Obsidian. Los agentes mutan el conocimiento mediante lwc, no editando .lwc/wiki.db o el Markdown proyectado directamente. Los comandos exitosos devuelven JSON en stdout; los fallos devuelven JSON estructurado en stderr.

Los comandos de lectura mantienen los almacenes de formato actual como solo lectura. Cuando un almacén escribible más antiguo se abre con una CLI más nueva, su esquema se migra transaccionalmente una vez antes de que continúe la lectura.

Recuperación Jerárquica y Grafo de Conocimiento

Cada fuente actual y página de Wiki se indexa determinísticamente como pasajes y oraciones. SQLite sigue siendo autoritativo; el FTS de tramos y un grafo de documentos externo opcional son índices reconstruidos. La búsqueda existente sigue siendo solo de documentos a menos que se solicite una granularidad:

lwc search "projection consistency" --granularity sentence --type page
lwc search "projection consistency" --granularity passage
lwc search "projection consistency" --granularity all --group-by document
lwc span get <SPAN_ID>
lwc span expand <SPAN_ID> --before 1 --after 1 --children 20

Los localizadores de tramos contienen la huella digital del documento y la versión de segmentación. Un localizador de un cuerpo reemplazado falla con stale_span e informa metadatos anteriores/actuales; LWC nunca lo reasigna silenciosamente a texto similar.

Usa la API de grafo acotada y tipada para exploración sin requerir palabras clave:

lwc graph explore                         # representative macro view
lwc graph node page:projection-policy
lwc graph neighbors page:projection-policy --direction outgoing
lwc graph path page:implementation page:policy --max-depth 6
lwc graph impact page:policy --max-depth 4
lwc graph overview
lwc graph status
lwc graph verify

Los bordes automáticos se limitan a hechos estructurales/evidenciales. Las afirmaciones semánticas deben ser explícitas y auditables:

lwc graph relation set page:implementation DEPENDS_ON page:policy \
  --provenance source-grounded --source 12 \
  --reason "Source 12 states the required policy" --confidence 0.95
lwc graph relation list --from page:implementation
lwc graph relation retract page:implementation DEPENDS_ON page:policy \
  --reason "The dependency was superseded"

Las razones de relaciones son contenido duradero: nunca pongas credenciales, secretos o cadenas de pensamiento crudas en ellas.

Los documentos SQLite siguen siendo autoritativos. El almacenamiento de grafos está deshabilitado por defecto; habilita exactamente un motor externo cuando se necesite recorrido. La configuración está en capas desde valores predeterminados integrados hasta archivos globales y de proyecto:

lwc config show
lwc config set --graph grafeo
lwc config set --graph surrealdb
lwc config set --graph disabled
lwc config unset --graph

La conversión de Markdown es una operación opt-in separada. lwc init informa la misma guía de configuración legible por máquina, pero nunca instala ni habilita un convertidor. Instala un adaptador, selecciónalo explícitamente, convierte a un nuevo archivo Markdown local, revísalo y solo entonces ingéstalo:

# Choose one adapter; both are disabled unless configured.
npm install --global @firecrawl/anydoc
lwc config set --trans anydoc

# Or:
python3 -m pip install 'markitdown[all]'
lwc config set --trans markitdown

lwc trans INPUT --output OUTPUT.md
lwc source add OUTPUT.md

La configuración acepta opciones --trans-timeout 1..900 y repetidas --trans-arg=<value> para el adaptador seleccionado. LWC invoca el ejecutable del adaptador fijo directamente, nunca recurre al otro adaptador, acepta solo archivos locales, limita la entrada y salida a 64 MiB y nunca sobrescribe una salida existente. Mantén las credenciales en el entorno del adaptador en lugar de en la configuración de LWC. Consulta la documentación oficial de Anydoc y MarkItDown para formatos compatibles y banderas opcionales.

Grafeo y SurrealDB integrado usan sidecars desechables bajo .lwc/. Cada trabajo de graph-project confirma una Fuente/Página actual y sus enlaces, citas y relaciones explícitas asociados antes de comenzar el siguiente documento. Las actualizaciones y eliminaciones ponen en cola solo los documentos afectados; la reconstrucción y reanudación usan las mismas unidades de documento. Las revisiones históricas de fuentes permanecen inmutables y nunca se re-tokenizan ni proyectan. Usa work list, work status o work watch para observar el progreso y work resume después de una interrupción. graph status informa el motor seleccionado y el recuento de documentos proyectados; graph verify compara sus claves de documentos actuales con SQLite.

Instalación

La mayoría de los usuarios deberían usar el prompt de configuración del Agente anterior. Los comandos manuales a continuación son para mantenedores, depuración o entornos de Agente que no pueden instalar la Skill complementaria.

Instala con Homebrew (las botellas precompiladas están disponibles para macOS con Apple silicon y Linux x86_64):

brew install JanYork/tap/lwc

Instala con npm (Node.js 22+):

npm install --global @i-xor/lwc

Instala desde crates.io:

cargo install --locked lwc

Instala desde GitHub:

curl --proto '=https' --tlsv1.2 -fsSL https://github.com/JanYork/llm-wiki-cli/releases/latest/download/install.sh | sh

El instalador admite macOS x86_64/aarch64, Linux glibc y Windows Git Bash, verifica la suma de verificación del lanzamiento e instala o actualiza lwc. Usa ~/.local/bin por defecto, o actualiza una copia existente en ~/.local/bin o ~/.cargo/bin. Para elegir otro directorio:

curl --proto '=https' --tlsv1.2 -fsSL https://github.com/JanYork/llm-wiki-cli/releases/latest/download/install.sh | LWC_INSTALL_DIR="$HOME/bin" sh

Alternativamente, compila e instala desde GitHub con Cargo:

cargo install --locked --git https://github.com/JanYork/llm-wiki-cli

O instala un checkout local:

git clone https://github.com/JanYork/llm-wiki-cli.git
cd llm-wiki-cli
cargo install --locked --path .

Skill de Agente Complementaria

El repositorio incluye skills/using-lwc, una Skill de Agente que convierte a lwc en una capa de memoria proactiva para sesiones sustanciales. Instálala desde skills.sh:

npx skills add JanYork/llm-wiki-cli --skill using-lwc -g

O cópiala desde un checkout local al directorio de Skills a nivel de usuario del runtime de Agente actual. Para Codex:

mkdir -p "$HOME/.agents/skills"
cp -R skills/using-lwc "$HOME/.agents/skills/"

La invocación canónica es $using-lwc.

Cuando se activa, la Skill:

• encuentra una CLI compatible o instala el lanzamiento oficial verificado por suma de verificación;
• inicializa la memoria global en ~/.lwc/ una vez;
• recupera contexto global y de proyecto acotado antes de la investigación repetida;
• inicializa el proyecto activo en invocación explícita, de lo contrario pregunta primero;
• rechaza escrituras de proyecto fuera de la raíz del espacio de trabajo autorizado actual;
• separa hechos del proyecto de conocimiento global reutilizable;
• integra fuentes y escribe respuestas duraderas de vuelta en la Wiki.

SKILL.md es un enrutador corto en lugar de un manual monolítico. Enlaza un documento de enseñanza enfocado para memoria básica, sincronización de activación, memoria activa, grafo de documentos físico, Word Graph acotado, CodeGraph, etiquetas fuertes, conversión de documentos, incorporación de Agentes y recuperación/mantenimiento. Cada documento establece cuándo usar y omitir la capacidad, su flujo de trabajo mínimo, límite de consentimiento y evidencia de finalización.

La Skill normalmente descubre el proyecto activo desde el directorio actual e invoca el comando lwc instalado globalmente directamente. LWC_PROJECT_ROOT es un límite explícito para un proyecto deliberadamente dirigido, no un prefijo para exportar para comandos rutinarios en el proyecto en el que ya estás trabajando.

Establece LWC_AUTO_INSTALL=0 para deshabilitar la instalación automática de la CLI. La instalación automática ejecuta el instalador revisado incluido en la Skill, confía en este repositorio y su límite de publicación de GitHub Release, y verifica el archivo descargado contra SHA256SUMS; la suma de verificación es protección de integridad, no firma de código del editor. Los binarios de lanzamiento cubren macOS x86_64/aarch64, Linux glibc y Windows a través de Git Bash. SKILL.md sigue el diseño de recursos de Agent Skills, mientras que agents/openai.yaml proporciona metadatos de OpenAI/Codex. La CLI en sí es neutral al runtime: cualquier Agente que pueda ejecutarla y cargar o adaptar las instrucciones de la Skill puede usar LWC. Los comandos de Skill, instrucciones globales y Hooks permanecen específicos del runtime, por lo que el prompt de configuración detecta y configura el host actual.

Configuración nativa del Agente

LWC puede detectar Agentes compatibles e instalar un MCP LWC unificado de solo lectura. Los 12 AgentTargets registrados son adaptadores sólidos: cada uno instala cada superficie oficial de MCP, Skill, Hook e Instructions basada en archivos disponible para ese host y alcance, mientras que las superficies propiedad de la UI, de vista previa o no compatibles se informan explícitamente.

lwc agent install --yes
lwc agent status --target all --location global
lwc agent install --print-config codex
lwc agent refresh --target codex,claude
lwc agent uninstall --target codex,claude --yes

--yes selecciona los Agents detectados, el ámbito global y los Hooks de ciclo de vida/prompt predeterminados de cada objetivo. Usa --no-prompt-hook para omitir el Hook por prompt de Claude. La entrada instalada es lwc -> serve --mcp; su única herramienta lwc_explore usa por defecto memoria Wiki acotada y acepta modos explícitos code/all. El projectPath solicitado debe permanecer dentro del espacio de trabajo donde el host MCP inició LWC. Nunca descarga ni inicializa CodeGraph. La instalación y actualización repetidas son byte-idempotentes; la desinstalación restaura solo el estado propio y deja intactos los índices del proyecto. Los paquetes opcionales de Codex, Claude Code y Pi residen en integrations/; instalar un paquete no concede ni elude la confianza nativa. No combines el instalador directo y el paquete nativo para el mismo Agent. Cada paquete nativo incluye la Skill using-lwc completa, por lo que la instalación no depende de un gestor de Skills de terceros ni de un entorno específico del mantenedor.

Pi expone LWC MCP a través de su puente de extensión oficial porque Pi no tiene MCP integrado. Otros Targets registran solo lwc serve --mcp; CodeGraph permanece como un plano interno de contexto de código de LWC y nunca se registra como un segundo MCP de Agent. Los ajustes de confianza y permisos administrados oficialmente por la UI siguen siendo gestionados por el usuario. Las superficies de vista previa se etiquetan como tales, y los ámbitos parciales de proyecto instalan las superficies compatibles en lugar de debilitar o rechazar todo el Target. Las rutas globales de Kiro respetan KIRO_HOME.

La interfaz de destino, el orden de registro, las reglas de detección y las rutas MCP siguen el diseño del adaptador de instalación con licencia MIT de CodeGraph; LWC añade el MCP LWC unificado, el informe de capacidades por superficie, Skills y Hooks, la propiedad de archivos compartidos y la reversión exacta. Ver THIRD_PARTY_NOTICES.md.

La salida de lwc init de un proyecto nuevo y los Hooks de sesión/compactación exponen hechos LWC_READINESS acotados para la Wiki, el grafo de documentos físico, el runtime e índice de proyecto de CodeGraph, además de comandos de integración de Agent. La disponibilidad del grafo físico distingue el consentimiento configurado de una proyección pendiente o fallida. La detección es de solo lectura y nunca habilita ni inicializa un grafo. Cuando ambos grafos requieren autorización, la línea base portable es texto plano, de modo que los Agents sin soporte de casillas se comportan igual:

1. Enable physical document graph and CodeGraph (recommended)
2. Enable physical document graph only
3. Enable CodeGraph only
4. Later

Tras la elección explícita 1, el Agent inicializa una Wiki de proyecto faltante, habilita Grafeo, espera y verifica su Work de proyección, inicializa CodeGraph y comprueba ambos resultados de forma independiente. Later no cambia nada y no bloquea la tarea principal. Los plugins nativos pueden mostrar los mismos IDs de elección con su propia UI, pero el soporte de casillas nunca es obligatorio.

Las etiquetas fuertes proporcionan carga acotada de páginas completas para reglas principales y runbooks:

lwc tag set "operations" incident-response --priority 100 --reason "primary runbook"
lwc load tag "operations" --limit 3
lwc tag autoload "operations" --enable --priority 100 --limit 3 \
  --max-chars 50000 --reason "required at session boundaries"

Este es un mecanismo explícito de carga fuerte, no una búsqueda derivada de tokens: los límites y presupuestos de caracteres se aplican antes de que las páginas completas entren en el contexto del Agent.

Inicio rápido

Esta sección documenta el protocolo CLI que ejecuta el Agent. Los humanos no necesitan ejecutar estos comandos durante el uso normal.

1. Inicializar una Wiki de proyecto

cd your-project
lwc init
printf '# Schema\nEvery page declares provenance; source-grounded claims cite sources.\n' | lwc schema set -
printf '# Purpose\nBuild a durable project Wiki.\n' | lwc purpose set -

La inicialización del proyecto añade la ruta .lwc/ relativa al proyecto al archivo local info/exclude de Git cuando es necesario, sin cambiar el .gitignore del repositorio. Usa lwc init --no-git-exclude solo cuando la Wiki está versionada intencionalmente.

2. Añadir material fuente

lwc source add-dir docs/

Los archivos sin título explícito usan su origen como respaldo estable y legible por humanos. Los bytes idénticos se deduplican mediante SHA-256. Las fuentes del proyecto que se resuelven fuera de la raíz activa de la Wiki requieren --allow-external-source. Los marcadores de credenciales de alta confianza se rechazan a menos que la fuente revisada se reconozca explícitamente con --acknowledge-sensitive-source.

Cada adición exitosa también registra la ruta de archivo observada y su instantánea inmutable actual. Comprueba solo las fuentes relevantes para la tarea antes de confiar en evidencia respaldada por archivos:

lwc source status 7 12

El comando transmite cada archivo vivo a través de SHA-256 e informa el linaje de ruta (current o superseded) por separado del estado del sistema de archivos (current, modified, missing, unreadable, oversized o unstable). Es de solo lectura. Usa source status --all solo para mantenimiento explícito porque su costo es proporcional a los bytes de todos los archivos rastreados. Inspecciona una ruta modificada antes de actualizar el conocimiento:

lwc source diff 7
lwc source refs 7 --limit 1000

source diff compara la fuente inmutable con su archivo vivo, o con otra instantánea mediante --to-source. Devuelve un diff unificado acotado: como máximo 8 MiB y 200 000 líneas por lado, 20 000 caracteres Unicode de salida por defecto y 100 000 con --max-chars. Si una fuente se observó en varias rutas, selecciona un --path exacto. Un diff truncado es solo una vista previa. source refs enumera los candidatos de revisión que citan directamente; no demuestra qué páginas se ven afectadas semánticamente. Vuelve a ejecutar source add solo después de la revisión cuando la misma ruta contiene una revisión nueva significativa. Una secuencia A -> B -> A sigue siendo tres observaciones de ruta aunque el contenido A reutilice su ID de fuente original. Las rutas vivas externas requieren --allow-external-source nuevamente; el texto vivo marcado también requiere --acknowledge-sensitive-source después de la inspección.

Las fuentes migradas de almacenes antiguos permanecen explícitamente sin rastrear porque LWC no adivina rutas históricas; vuelve a añadir el archivo previsto una vez para establecer su primera revisión rastreada. Si un archivo o la cabecera de una ruta cambia durante la comprobación, LWC devuelve source_status_unstable; reintenta en lugar de confiar en un resultado de tiempo mixto.

Para una importación atómica curada, las rutas de un manifiesto JSON se resuelven desde el directorio del manifiesto:

{
  "sources": [
    {"path": "ARCHITECTURE.md", "title": "Architecture contract"},
    {"path": "src/store.rs", "title": "SQLite store"}
  ]
}

lwc source add-manifest lwc-sources.json

3. Analizar e integrar una fuente

lwc ingest next --context-limit 50 --source-max-chars 100000
lwc ingest analyze 1 --file analysis.md

Usa lwc ingest claim 7 cuando un manifiesto o programador ya haya seleccionado un ID de fuente pendiente exacto.

Si source_window.has_more es verdadero, continúa leyendo desde source_window.next_offset_chars:

lwc source show 1 --offset-chars 100000 --max-chars 100000

Crea una página de resumen de fuente citada e integra su contribución en al menos una página que no sea de fuente antes de completar la tarea de ingesta:

lwc page put source-1 \
  --title "Source 1 Summary" \
  --kind source \
  --summary "What this source contributes" \
  --file source-summary.md \
  --source 1

lwc page put durable-concept \
  --title "Durable Concept" \
  --kind concept \
  --summary "How this source changes shared knowledge" \
  --file concept.md \
  --source 1

lwc ingest complete 1

Ambas capas son obligatorias: la página de fuente es una ayuda de navegación y procedencia; la página no fuente hace que el conocimiento se acumule. Si una fuente realmente no cambia ninguna página compartida, complétala con una explicación específica auditada:

lwc ingest complete 1 \
  --no-derived-pages-reason "Duplicate evidence; existing synthesis already covers every supported claim"

Las citas de fuente exponen automáticamente la procedencia source-grounded. Para conocimiento duradero que proviene del usuario, de una observación del Agent o de una hipótesis explícita, repite --provenance según sea necesario en lugar de inventar una fuente:

lwc page put architecture-decision \
  --title "Architecture decision" \
  --kind query \
  --summary "Accepted constraint and remaining uncertainty" \
  --file decision.md \
  --provenance user-provided \
  --provenance hypothesis

page put reemplaza el conjunto completo de citas y procedencia explícita. Lee primero la página existente y luego repite cada valor --source y --provenance no fuente que siga siendo válido. No pases source-grounded explícitamente; se deriva de las citas. La procedencia se devuelve mediante lecturas de página, contexto, búsqueda, referencias de fuente y proyección Markdown, pero no cambia la clasificación de búsqueda.

4. Consultar la Wiki acumulada

lwc context --limit 50
lwc search "question keywords" --limit 20
lwc search "question keywords" --limit 20 --explain
lwc search "concept only" --type page --kind concept
lwc search "exact evidence" --type source
lwc page show source-1

Flujo de trabajo del Agent

El flujo de trabajo previsto es:

1. Recopilar fuentes inmutables.
2. Reclamar una tarea de ingesta con lwc ingest next acotado, o ingest claim <ID> cuando la fuente se seleccionó explícitamente.
3. Leer cada ventana de fuente devuelta, además del esquema, el propósito y el contexto acotado.
4. Analizar antes de generar páginas.
5. Escribir o revisar un resumen de fuente y páginas duraderas compartidas con citas explícitas --source.
6. Completar solo después de que ambas puertas de integración pasen, o registrar por qué ninguna página compartida debería cambiar.
7. Poner una ingesta de varios comandos o una revisión amplia en un solo changeset, validar el borrador y luego publicarlo atómicamente.
8. Usar search, context, graph y lint para mantener la Wiki coherente con el tiempo.

Ver docs/agent-workflow.md para el contrato operativo completo. Ejecuta lwc --help o lwc <command> --help para precondiciones orientadas al Agent, transiciones de estado, efectos secundarios y próximas acciones.

Cambios atómicos de varios comandos

Un solo comando source o page es transaccional. Usa un changeset cuando una actualización lógica necesite varios comandos y no deba exponer una Wiki parcial:

lwc --scope project changeset begin architecture-refresh
lwc --scope project --changeset architecture-refresh source add-manifest sources.json
lwc --scope project --changeset architecture-refresh ingest claim 1
# Analyze, write cited pages, and complete ingest with the same selector.
lwc --scope project --changeset architecture-refresh lint
lwc --scope project --changeset architecture-refresh search "expected answer" --limit 5
lwc --scope project changeset show architecture-refresh
lwc --scope project changeset commit architecture-refresh

Las lecturas de borrador ven escrituras en etapas, mientras que SQLite y Markdown en vivo permanecen sin cambios. La base de datos del borrador comienza como un pequeño superposición dispersa; no copia ni hace checkpoint de la Wiki en vivo. changeset show informa operaciones en etapas, revisiones y disponibilidad sin ejecutar lint. El commit valida y aplica solo las entidades tocadas, por lo que las escrituras en vivo no relacionadas sobreviven; un conflicto de revisión de la misma entidad falla sin sobrescribir ninguno de los dos lados. El commit rechaza borradores vacíos y problemas de lint; no hay fuerza ni fusión automática. Usa --allow-lint-issues --reason "reviewed pre-existing debt" solo para deuda auditada que el changeset no introdujo. Después del commit, vuelve a ejecutar las mismas comprobaciones de recuperación fijas contra el estado en vivo. El commit congela el borrador revisado antes de la publicación; changeset_frozen bloquea cualquier escritura en etapas posterior. Reintenta el mismo commit para la recuperación, o descarta después de un conflicto informado; nunca añadas más trabajo a un borrador congelado.

lwc --scope project changeset discard architecture-refresh
lwc --scope project changeset rollback <CHANGESET_ID>

El descarte toca solo un borrador no confirmado. El commit escribe un parche inverso con checksum que contiene solo las entidades tocadas y devuelve el ID de reversión exacto; la reversión restaura solo esas entidades y se niega si una cambió nuevamente. Los changesets de proyecto y globales son separados, --scope all no es válido, y init, maintenance, checkpoint y los comandos de changeset anidados rechazan --changeset. Los borradores nunca crean una segunda proyección Markdown. Si un error estructurado informa committed=true con trabajo de limpieza o materialización pendiente, no repitas los cambios de conocimiento; ejecuta la acción de recuperación devuelta.

El commit disperso actualmente tiene parches exactos para add/ingesta de Source, put/remove de Page, esquema, propósito y operaciones de búsqueda registradas. Las mutaciones de peso de recuperación y relaciones semánticas explícitas fallan antes del checkpoint o de tomar un bloqueo de escritura en vivo con changeset_sparse_unsupported; aplícalas como transacciones directas de entidad única hasta que sus parches inversos dispersos estén disponibles.

Ámbitos

lwc admite tres ámbitos:

Ejemplos:

lwc --scope global init
lwc --scope global source add shared.md
lwc --scope all search "shared term"
lwc --scope all context

Las escrituras de conocimiento son explícitas. all no crea citas o enlaces implícitos entre almacenes; search --record solo añade la operación de consulta a cada almacén seleccionado.

Búsqueda y CJK

La búsqueda es léxica y determinista.

• Los términos de búsqueda son texto plano, no sintaxis FTS sin procesar.
• --type auto es el valor predeterminado: las páginas compiladas aparecen primero, las fuentes sin procesar emparejadas están ocultas y las fuentes sin procesar proporcionan recuperación de respaldo.
• Use --type page, --type source o --type all para seleccionar una capa. Repita --kind para restringir los resultados de página, como --kind concept --kind synthesis.
• Los términos de consulta CJK de varios caracteres usan bigramas adyacentes; el índice también conserva unigramas que no son palabras vacías para que las consultas de un carácter sigan siendo buscables.
• El texto en latín se tokeniza en términos alfanuméricos en minúsculas.
• La clasificación mantiene distintos el título, el nombre del archivo fuente, la ruta/slug, el resumen y la evidencia del cuerpo. Las coincidencias exactas/parciales de título y ruta reciben aumentos limitados.
• Los documentos README/índice/descripción general y los centros de navegación explícitos reciben una reducción de peso condicional a la consulta en favor de documentos de características específicas; preguntar por el README o la descripción general desactiva esa penalización.
• Los candidatos de página pueden recibir un aumento limitado de enlace directo o de gráfico de fuente compartida. Las relaciones solo de vecinos comunes no pueden cambiar el orden de búsqueda, y un centro de navegación amplio recibe una penalización de gráfico limitada.
• --explain devuelve la aritmética exacta de la puntuación, incluidos los indicadores léxicos, genéricos, de gráfico, de peso manual y de retroalimentación de consulta. No registra la consulta; --record sigue siendo la única opción de participación en el historial de búsqueda.
• Los coeficientes fijos y las clasificaciones de menor-es-mejor mantienen los resultados de proyecto y globales comparables bajo --scope all.

Esto es intencionalmente sin diccionario. El objetivo es un comportamiento estable para nombres de productos, nombres en clave, términos en idiomas mixtos y vocabulario emergente sin depender de un diccionario de segmentación de palabras.

Pesos de recuperación explícitos y retroalimentación

Use un peso de documento para un juicio duradero e independiente de la consulta sobre una página o fuente. Use retroalimentación para una huella de consulta exacta de tokens ordenados:

lwc weight set page payment-rules \
  --value 2 \
  --reason "Canonical payment rules specification" \
  --provenance agent-observed
lwc weight list page payment-rules

lwc weight feedback page payment-rules \
  --query "payment reconciliation rules" \
  --signal relevant \
  --reason "Verified against the expected answer" \
  --provenance agent-observed

lwc weight feedback-clear page payment-rules \
  --query "payment reconciliation rules" \
  --provenance agent-observed
lwc weight clear page payment-rules --provenance agent-observed

Los valores de documento son -2, -1, 1 o 2; use clear para cero. Ambos mecanismos solo reclasifican candidatos léxicos y no pueden hacer que aparezca un documento que no coincide. Una fila user-provided tiene prioridad sobre una fila agent-observed mientras ambas sigan siendo auditables. La retroalimentación almacena la huella SHA-256, no la consulta sin procesar, y no se transfiere a paráfrasis con tokens diferentes. Las razones y los registros de operaciones son duraderos, así que nunca copie una consulta sensible en --reason. Las mutaciones requieren un ámbito project o global explícito; --scope all se rechaza.

Visor de solo lectura y CodeGraph

lwc view inicia un inspector de proyecto en primer plano, solo de loopback, y abre el navegador. Sirve una aplicación integrada de TS + Lit (sin CDN y sin runtime de Node en el momento de uso) y expone solo APIs GET/HEAD. Las páginas, fuentes, Markdown, el grafo de conocimiento y el grafo de código opcional se leen del proyecto actual sin migración, actualización ni construcción de grafo:

lwc view
lwc view --port 4173 --no-open

El visor se inicia en inglés. Use el control 中文 / EN para cambiar de idioma; el navegador recuerda la selección mientras el contenido de Wiki permanece en su idioma de autoría. Los grafos usan una única vista de relaciones 3D inspirada en Obsidian con nodos pequeños, etiquetas persistentes, enlaces delgados, rotación y zoom.

La indexación de código es solo de proyecto y está deshabilitada hasta que se inicialice explícitamente. La bifurcación fijada de LWC CodeGraph se descarga una vez desde su GitHub Release, se verifica con SHA-256 y se almacena en caché bajo ~/.lwc/runtime/codegraph/<PIN>/<TARGET>/; cada proyecto mantiene solo su índice bajo .lwc/codegraph. La telemetría siempre está desactivada y no se usa ningún estado .codegraph.

lwc cg status
lwc cg init                 # download once, then index one complete file at a time
lwc cg sync
lwc cg query UserService
lwc cg node UserService
lwc cg callers UserService
lwc cg callees UserService
lwc cg impact UserService
lwc cg files

El runtime fijado reconoce estos lenguajes y formatos orientados a código: TypeScript, TSX, JavaScript, JSX, ArkTS, Python, Go, Rust, Java, C, C++, C#, Razor, PHP, Ruby, Swift, Kotlin, Dart, Svelte, Vue, Astro, Liquid, Pascal, Scala, Lua, Luau, Objective-C, R, Solidity, Nix, YAML, Twig, XML, .properties, CFML, CFScript, CFQuery, COBOL, VB.NET, Erlang y Terraform. YAML, Twig y .properties se rastrean a nivel de archivo; los resolutores de framework aún pueden agregar relaciones. XML se reconoce para la extracción de mapeadores MyBatis.

Todas las capacidades de consulta de CodeGraph se reenvían mediante lwc cg. Los comandos globales de ciclo de vida (install, uninstall, upgrade, telemetry, daemon, daemons) están bloqueados. El puente exacto lwc cg serve --mcp permanece para compatibilidad manual heredada; las nuevas integraciones de Agent usan lwc serve --mcp, que fusiona la exploración limitada de Wiki y CodeGraph detrás de una sola herramienta de solo lectura. LWC posee el runtime y aplica el límite del proyecto. Las escrituras iniciales, incrementales, completas, de actualización, de eliminación, de resolución de referencias y de recuperación confirman un archivo propietario por completo antes del siguiente; el grafo actual permanece legible y las revisiones históricas de documentos nunca se actualizan.

Mantenimiento y Proyección

Comandos de mantenimiento útiles:

lwc lint
lwc maintenance reindex
lwc maintenance materialize
lwc maintenance compact
lwc work list
lwc work status <WORK_ID>
lwc work watch <WORK_ID>
lwc work cancel <WORK_ID>
lwc work resume <WORK_ID>
lwc checkpoint create before-large-update
lwc checkpoint list
lwc log --limit 20

Notas:

• Los comandos de mantenimiento devuelven un work duradero inmediatamente. Lea el progreso con work status, o use work watch e inspeccione work.result después del éxito. La migración de esquema v10 a v11 usa el mismo mecanismo automáticamente, por lo que los comandos normales nunca realizan esa migración en línea.
• lint es de solo lectura por defecto. Agregue --record solo cuando la pasada de lint pertenezca al historial de operaciones duraderas.
• maintenance reindex reconstruye los artefactos de búsqueda derivados desde SQLite.
• maintenance materialize reconstruye el árbol de Markdown proyectado desde SQLite.
• maintenance compact solo intenta un checkpoint de truncamiento WAL; no oculta una optimización FTS completa. Ejecútelo mientras la Wiki esté inactiva e inspeccione busy más after_bytes. Un lector ocupado regresa rápidamente sin cambiar el contenido canónico.
• Las consultas de búsqueda son privadas por defecto; agregue --record solo cuando desee que la redacción de la consulta se almacene en el registro de operaciones duraderas.

lwc checkpoint create <NAME> usa la API de copia de seguridad en línea de SQLite. Restaure con lwc checkpoint restore <NAME>; LWC primero crea un checkpoint de seguridad pre-restore-* y luego reconstruye la proyección. Use source remove <ID> y page remove <SLUG> para la eliminación protegida: se rechazan las fuentes con citas y las páginas con enlaces entrantes. Eliminar la fuente actual de una ruta rastreada detiene el rastreo de esa ruta en lugar de exponer silenciosamente una revisión anterior como actual.

Para una ingesta de múltiples fuentes o un reemplazo amplio de páginas, prefiera un changeset sobre un checkpoint manual: una confirmación exitosa escribe un parche inverso disperso, publica solo las entidades canónicas afectadas en una transacción y materializa incrementalmente el Markdown cambiado. La confirmación intenta un truncamiento WAL después de la publicación; wal_checkpointed=false significa que un lector activo lo impidió y no significa que la confirmación canónica falló.

Para una copia de seguridad externa del sistema de archivos, detenga los comandos lwc activos y copie el directorio completo .lwc/. No copie solo wiki.db mientras un escritor pueda estar usando sus archivos WAL.

Suite de Benchmarks

El benchmark opcional importa un corpus UTF-8 local en una Wiki temporal e informa el tiempo de importación, P50/P95 de búsqueda, Recall@5/10, MRR y almacenamiento antes/después de la compactación. La verdad fundamental es un archivo JSONL de consultas y rutas relativas al corpus esperadas:

cargo build --release
LWC_BENCH_CORPUS=/path/to/sanitized-corpus \
LWC_BENCH_QUERY_SET=/path/to/query-set.jsonl \
LWC_BENCH_BINARY="$PWD/target/release/lwc" \
cargo test --test search_benchmark -- --ignored --nocapture

El cargo test --all-targets normal cubre búsqueda de página primero, filtros de tipo/tipo, ventanas de fuente UTF-8, compuertas de finalización de ingesta, precisión de grafo, migraciones, lint y compactación WAL. Consulte benchmarks/README.md para el contrato de carga de trabajo y las reglas justas de comparación antes/después.

Límites y No-Objetivos

Restricciones de diseño actuales:

• base de conocimiento de una sola máquina y un solo usuario;
• flujo de trabajo de texto UTF-8;
• tamaño de entrada limitado a 64 MiB por esquema, propósito, fuente o cuerpo de página;
• búsqueda léxica, no recuperación vectorial semántica.

No-objetivos deliberados para este CLI:

• sin llamadas LLM integradas;
• sin base de datos vectorial;
• sin demonio ni servicio en segundo plano;
• sin interfaz web ni de escritorio;
• sin contrato directo de edición de base de datos.

Si el Markdown proyectado se desvía, reconstruyalo. Si el esquema SQLite es incorrecto, corríjalo a través del CLI y las migraciones, no a mano.

Contribuciones

Las issues y pull requests son bienvenidas, especialmente en torno a:

• ergonomía del flujo de trabajo de agentes;
• comportamiento de proyección determinista;
• contratos duraderos de citas y mantenimiento de páginas;
• calidad de búsqueda para corpus técnicos multilingües.

Lea CONTRIBUTING.md antes de abrir una pull request. Informe problemas de seguridad según SECURITY.md.

Licencia

Licenciado bajo la Apache License 2.0.