lossless-claw

lossless-claw

Plugin di Gestione del Contesto Senza Perdite (Lossless Context Management - LCM) per OpenClaw, basato sul paper LCM di Voltropy. Sostituisce la compattazione a finestra scorrevole integrata di OpenClaw con un sistema di riassunto basato su DAG che preserva ogni messaggio mantenendo il contesto attivo entro i limiti dei token del modello.

Cosa fa

Ci sono due modi per capire cosa fa: leggere quanto segue o guardare questa super cool visualizzazione animata.

Quando una conversazione supera la finestra di contesto del modello, OpenClaw (come tutti gli altri agenti) normalmente tronca i messaggi più vecchi. LCM invece:

1. Persiste ogni messaggio in un database SQLite, organizzato per conversazione.
2. Riassume i blocchi di messaggi più vecchi in sintesi utilizzando il tuo LLM configurato.
3. Condensa i riassunti in nodi di livello superiore man mano che si accumulano, formando un DAG (grafo aciclico diretto).
4. Assembla il contesto ad ogni turno combinando riassunti + messaggi recenti non elaborati.
5. Fornisce strumenti (lcm_grep, lcm_describe, lcm_expand) in modo che gli agenti possano cercare e richiamare dettagli dalla storia compattata.

Nulla viene perso. I messaggi originali rimangono nel database. I riassunti si collegano ai loro messaggi sorgente. Gli agenti possono approfondire qualsiasi riassunto per recuperare il dettaglio originale.

Sembra di parlare con un agente che non dimentica mai. Perché non lo fa. In condizioni operative normali, non dovrai più pensare alla compattazione.

Comandi e Skill

Il plugin ora include una skill lossless-claw e una piccola superficie di comando per i provider di comandi chat/nativi di OpenClaw supportati:

Questi sono comandi slash/nativi del plugin, non sottocomandi CLI di root shell. Esempi supportati:

• /lcm
• /lcm backup
• /lcm rotate
• /lcm doctor
• /lcm doctor clean
• /lossless

Non supportati attualmente come comandi CLI di root:

• openclaw lcm
• openclaw lossless
• openclaw /lcm

La skill inclusa si concentra sulla configurazione, sulla diagnostica, sull'architettura e sull'uso degli strumenti di richiamo. Il suo set di riferimento si trova sotto skills/lossless-claw/references/.

Avvio Rapido

Prerequisiti

• OpenClaw con supporto per il motore di contesto dei plugin
• Node.js 22+
• Un provider LLM configurato in OpenClaw (utilizzato per la creazione di riassunti)

Installare il plugin

Usa l'installer dei plugin di OpenClaw (raccomandato):

openclaw plugins install @martian-engineering/lossless-claw

Se stai eseguendo da un checkout locale di OpenClaw, usa:

pnpm openclaw plugins install @martian-engineering/lossless-claw

Per lo sviluppo locale del plugin, costruisci prima la tua copia di lavoro, quindi collegala invece di copiare i file:

cd /path/to/lossless-claw
pnpm build

openclaw plugins install --link /path/to/lossless-claw
# o da un checkout locale di OpenClaw:
# pnpm openclaw plugins install --link /path/to/lossless-claw

Esegui nuovamente pnpm build dopo le modifiche al codice locale in modo che l'output dist/ del plugin collegato rimanga aggiornato.

Il comando di installazione registra il plugin, lo abilita e applica la selezione di slot compatibili (incluso contextEngine quando applicabile).

Nota: Se la tua configurazione OpenClaw utilizza plugins.allow, inserisci nella 'whitelist' l'ID del plugin lossless-claw più tutti gli altri plugin attivi su cui fai affidamento. Non aggiungere token di comando o alias come lossless o /lcm a plugins.allow; questa impostazione accetta solo ID di plugin. In alcune configurazioni, la restrizione della 'whitelist' può impedire il caricamento di integrazioni basate su plugin, anche se lossless-claw stesso è installato correttamente. Riavvia il gateway dopo le modifiche alla configurazione del plugin.

Configurare OpenClaw

Nella maggior parte dei casi, non sono necessarie modifiche manuali al JSON dopo openclaw plugins install.

Se è necessario impostarlo manualmente, assicurati che lo slot del motore di contesto punti a lossless-claw:

{
  "plugins": {
    "slots": {
      "contextEngine": "lossless-claw"
    }
  }
}

Riavvia OpenClaw dopo le modifiche alla configurazione.

Configurazione

LCM è configurato tramite una combinazione di configurazione del plugin e variabili d'ambiente. Le variabili d'ambiente hanno la precedenza per la compatibilità con le versioni precedenti.

Configurazione del plugin

Aggiungi una voce lossless-claw sotto plugins.entries nella tua configurazione OpenClaw:

{
  "plugins": {
    "entries": {
      "lossless-claw": {
        "enabled": true,
        "llm": {
          "allowModelOverride": true,
          "allowedModels": ["openai/gpt-5.4-mini"]
        },
        "config": {
          "freshTailCount": 64,
          "leafChunkTokens": 80000,
          "newSessionRetainDepth": 2,
          "contextThreshold": 0.75,
          "incrementalMaxDepth": 1,
          "cacheAwareCompaction": {
            "enabled": true,
            "cacheTTLSeconds": 300
          },
          "ignoreSessionPatterns": [
            "agent:*:cron:**"
          ],
          "transcriptGcEnabled": false,
          "proactiveThresholdCompactionMode": "deferred",
          "summaryModel": "openai/gpt-5.4-mini",
          "expansionModel": "openai/gpt-5.4-mini",
          "delegationTimeoutMs": 300000,
          "summaryTimeoutMs": 60000
        }
      }
    }
  }
}

leafChunkTokens controlla quanti token sorgente possono accumularsi in un blocco di compattazione 'foglia' prima che venga attivata la riassunzione. Il valore predefinito è 20000, ma i provider di riassunti con quota limitata potrebbero beneficiare di un valore maggiore per ridurre la frequenza di compattazione. summaryModel e summaryProvider consentono di richiedere un modello di compattazione più economico o più veloce tramite la capacità api.runtime.llm.complete di OpenClaw; OpenClaw gestisce comunque la spedizione e l'autenticazione del provider. Le richieste esplicite di modelli di riassunto richiedono llm.allowModelOverride e voci di policy llm.allowedModels corrispondenti per lossless-claw. expansionModel fa lo stesso per le chiamate del sub-agente lcm_expand_query (che si approfondiscono nei riassunti per recuperare i dettagli). delegationTimeoutMs controlla per quanto tempo lcm_expand_query attende il completamento del sub-agente delegato prima di restituire un errore di timeout; il valore predefinito è 120000 (120s). summaryTimeoutMs controlla il timeout per chiamata per la riassunzione LCM basata su modello; il valore predefinito è 60000 (60s). Se non impostato, le impostazioni del modello tornano comunque al modello/provider predefinito configurato di OpenClaw. Vedere Requisiti di override del modello di espansione per la policy di fiducia del subagent richiesta quando si usa expansionModel.

Variabili d'ambiente

Le riscritture GC della trascrizione sono disabilitate per impostazione predefinita. Imposta transcriptGcEnabled o LCM_TRANSCRIPT_GC_ENABLED per attivarle esplicitamente. La compattazione proattiva differita è anche l'impostazione predefinita. Imposta proactiveThresholdCompactionMode o LCM_PROACTIVE_THRESHOLD_COMPACTION_MODE su inline solo se hai bisogno del comportamento di compattazione in primo piano legacy. In modalità differita, lossless-claw registra un elemento di debito che modifica il prompt dopo il turno, lascia che il maintain() in background elabori solo il lavoro che non modifica il prompt mentre la cache Anthropic è ancora 'calda', e quindi consuma quel debito prima dell'assemblaggio una volta che la cache è 'fredda' o il prompt si sta avvicinando al overflow.

Requisiti di override del modello di espansione

Se desideri che lcm_expand_query venga eseguito su un modello dedicato tramite expansionModel o LCM_EXPANSION_MODEL, OpenClaw deve fidarsi esplicitamente del plugin per richiedere override del modello del sub-agente.

Per la maggior parte delle configurazioni, openai/gpt-5.4-mini è un punto di partenza migliore di Anthropic Haiku perché è economico, veloce e non dipende dalla quota Anthropic rimanente.

Aggiungi una policy subagent sotto plugins.entries.lossless-claw e inserisci nella 'whitelist' il target provider/model canonico che desideri che il plugin utilizzi:

{
  "models": {
    "openai/gpt-4.1-mini": {}
  },
  "plugins": {
    "entries": {
      "lossless-claw": {
        "enabled": true,
        "subagent": {
          "allowModelOverride": true,
          "allowedModels": ["openai/gpt-4.1-mini"]
        },
        "config": {
          "expansionModel": "openai/gpt-4.1-mini"
        }
      }
    }
  }
}

• subagent.allowModelOverride è richiesto affinché OpenClaw onori gli override provider/model per esecuzione richiesti dal plugin.
• subagent.allowedModels è opzionale ma raccomandato. Usa "*" solo se intendi fidarti intenzionalmente di qualsiasi modello target.
• Il target di espansione scelto deve essere anche disponibile nel normale catalogo modelli di OpenClaw. Se non è già configurato altrove, aggiungilo sotto la mappa models di primo livello come mostrato sopra.
• Se preferisci dividere provider e modello, imposta config.expansionProvider e usa un config.expansionModel 'bare'.

Equivalenti di configurazione del plugin:

• ignoreSessionPatterns
• statelessSessionPatterns
• skipStatelessSessions
• transcriptGcEnabled
• newSessionRetainDepth
• summaryModel
• summaryProvider
• delegationTimeoutMs
• summaryTimeoutMs

Le variabili d'ambiente hanno comunque la precedenza sulla configurazione del plugin quando entrambe sono impostate.

Priorità del modello di riassunto

Per la riassunzione di compattazione, lossless-claw risolve il modello in questo ordine:

1. LCM_SUMMARY_MODEL / LCM_SUMMARY_PROVIDER
2. Configurazione del plugin summaryModel / summaryProvider
3. Modello/provider di compattazione predefinito di OpenClaw
4. Suggerimenti di modello/provider di runtime/sessione da OpenClaw

Se summaryModel include già un prefisso di provider come anthropic/claude-sonnet-4-20250514, summaryProvider viene ignorato per quella scelta. Altrimenti, il provider torna all'override corrispondente, quindi OPENCLAW_PROVIDER, quindi il provider inferito dal chiamante.

Le chiamate di riassunto vengono inviate tramite lo strato LLM di runtime di OpenClaw, quindi i profili di autenticazione, il refresh OAuth, le chiavi API, gli URL base e la preparazione delle richieste specifiche del provider rimangono di proprietà dell'host. Esegui openclaw doctor --fix dopo aver aggiunto override espliciti del modello di riassunto se vuoi che OpenClaw aggiunga la policy plugins.entries.lossless-claw.llm corrispondente.

Configurazione iniziale raccomandata

LCM_FRESH_TAIL_COUNT=64
LCM_LEAF_CHUNK_TOKENS=2000