RecallLoom
RecallLoom ist ein portabler Kontextrahmen für sitzungsbasierte Agenten.
Es bietet ein leichtgewichtiges Dateimodell für die Projektkontinuität über mehrere Sitzungen hinweg, ohne schwere Infrastruktur zu benötigen.
Das Ziel ist nicht, alles zu merken. Das Ziel ist, den richtigen Projektzustand dauerhaft, lesbar und wiederherstellbar über Sitzungen hinweg zu halten.
Paketumfang
Diese Datei ist der agentenseitige Einstiegspunkt für das installierbare recallloom/ Skill-Paket.
Installieren und auslösen dieses Pakets über den normalen Skill-Erkennungsprozess Ihres Host-Agenten. RecallLoom selbst benötigt keinen benutzerdefinierten hostspezifischen Launcher im Paket. Das Paket kann dennoch optionale native Wrapper-Vorlagen für unterstützte Hosts enthalten.
Dieses installierbare Paket ist bewusst schlank gehalten. Menschlich lesbare Repository-Landingpages und Marketing-Dokumente können upstream existieren, sind aber nicht in das installierte Skill-Verzeichnis gebündelt.
Im Quellrepository sind README.md und README.en.md prägnante öffentliche Eingangstüren, README.zh-CN.md ist der Kompatibilitätseintrag, INDEX.md ist die vollständige Karte und USAGE.md ist die Bedienungsanleitung.
Diese Dateien beschreiben denselben Helfervertrag wie dieser installierte Paket-Einstiegspunkt, anstatt eine zweite Logikmenge zu definieren.
Für Paketbestand, Protokolldetails und Helfer-Skriptverhalten verlassen Sie sich auf die Dateien, die innerhalb des Pakets ausgeliefert werden:
managed-assets.jsonpackage-metadata.jsonreferences/file-contracts.mdreferences/operation-playbooks.mdreferences/package-support-policy.mdreferences/recording-workflow.mdreferences/protocol.md
Paketfakten
- Paketversion:
0.4.6.1 - Protokollversion:
1.0 - unterstützte Protokollversionen:
1.0
Laufzeitannahmen
- Python 3.10 oder neuer
- unterstützte Workspace-Sprachen:
enzh-CN
- unterstützte Brückenziele:
AGENTS.mdCLAUDE.mdGEMINI.md.github/copilot-instructions.md
Paket-Support-Gate
Die RecallLoom-Paketunterstützung ist getrennt von der Projekt-Sidecar-Protokollkompatibilität.
- Helfer MÜSSEN die Paketunterstützungsprüfung durchführen und DÜRFEN den Support-Status NICHT in das Projekt
.recallloom/schreiben. - Wenn die Unterstützung
readonly_onlyist, MÜSSEN mutierende Helfer blocken, während diagnostische und schreibgeschützte Helfer FORTSETZEN DÜRFEN. - Wenn die Unterstützung
diagnostic_onlyist, SOLLTEN nur diagnostische Helfer FORTSETZEN. - Wenn die Unterstützung
unknown_offlineist, DÜRFEN diagnostische und schreibgeschützte Aktionen FORTSETZEN, aber mutierende Aktionen MÜSSEN blocken, bis die Unterstützung verifiziert werden kann. - Blockierte Aktionen MÜSSEN den gemeinsamen Fehlervertrag mit
blocked_reason: package_support_blockedund einempackage_support-Objekt zurückgeben. Siehereferences/package-support-policy.md.
Öffentliche Oberfläche und erforderliche Prüfungen
- Öffentliche Paket- und Release-Oberflächen MÜSSEN auf Dateien beschränkt bleiben, die ein Benutzer zum Installieren, Verstehen und Betreiben des Pakets benötigt.
- Öffentliche Oberflächen DÜRFEN KEINE kopierten Projektspeicher, generierte Laufzeitausgaben, maschinenlokale Daten, Nur-Maintainer-Arbeitsdateien oder Material enthalten, das nicht für das installierbare Paket erforderlich ist.
- Öffentliche CI und erforderliche Prüfungen DÜRFEN Repository-Inhalte und Metadaten validieren.
- Die Formulierung erforderlicher Prüfungen DARF Repository-Prüfungen NICHT als Beweis für den lokalen Workspace-Zustand, das Hostverhalten oder den Sidecar-Vertrauensstatus eines Benutzers darstellen.
Nicht-invasive Standardeinstellungen und UX-Gates
- Kerninstallation und tägliche Nutzung DÜRFEN KEINE Hooks, Daemons, Watcher, MCP/Plugin-Erzwingung, Host-Adapter, Telemetrie/Metriken oder Remote-Payload-Übertragung erfordern oder automatisch installieren.
- Native Befehls-Wrapper sind optionale Komfort-Einstiegspunkte über demselben Dispatcher, keine erforderliche Erzwingungsebene.
- Normale Dokumente/Quellcode/Planungsbearbeitungen außerhalb des verwalteten Sidecars bleiben still erlaubt oder mit geringem Aufwand verbunden, es sei denn, sie betreffen den herkunftsempfindlichen RecallLoom-Zustand.
- Verwaltete Sidecar- oder herkunftsbeeinflussende Aktionen zeigen bei relevanter Herkunftsrelevanz eine der Optionen
allow,warn,askoderblockin der Bereitschaftsausgabe des Helfers an. warngilt für risikoarme, nur strukturelle oder lesbare Legacy-Zustände und sollte kurz bleiben; wiederholte, risikoarme Warnungen innerhalb derselben Sitzung sollten eine Abkühlungsfunktion haben.askgilt für Legacy-Review-/Reparaturimport oder überprüfte importierte Basislaufaktionen und erfordert explizite Bedienerbestätigung vor risikoreicheren Schreibvorgängen.blockist nicht verzichtbar bei gefälschten Markierungen, festgestellten Empfangs-/Speicherinkonsistenzen, direktenstate.json-/config.json-Bearbeitungen, Datenschutzverletzungen und jedem Zustand, der alsinconsistent_or_tampered_evidenceklassifiziert ist.- Stellen Sie Remote-Dienste, Hostspeicher, Plugins, MCP, Hooks oder Wrapper NICHT als Autorität für lokale Helferbeweise dar.
- Empfangsgestützte Mutation beschränkt sich auf vom Dispatcher ausgestellte verwaltete Dateischreibvorgänge, das Anhängen an tägliche Logs an den aktuellsten Cursor und das Synchronisieren von Zusammenfassungen nach dem Anhängen. Archiv- und Brückenanwendung bleiben in der Vorschau, bis diese Oberflächen ihre eigene Empfangsunterstützung erhalten.
Schreibprotokoll-Rote Linien
- Verwaltete Sidecar-Schreibvorgänge MÜSSEN Helfer-Skripte verwenden. Umgehen Sie diese NICHT mit blindem Dateiaustausch, blindem Patchen oder handgebauten Sidecar-Dateien.
- Tägliche Log-Schreibvorgänge MÜSSEN
append_daily_log_entry.pyoder den Dispatcherappendverwenden. Handschreiben Sie KEINEdaily-log-entry-Markierungen. - Die Reparatur des täglichen Log-Cursors MUSS
repair_daily_log_cursor.pyoder den Dispatcherrepair-daily-log-cursorverwenden. Bearbeiten Siestate.json.daily_logsNICHT von Hand. - Verwaltete Dateien im Überschreibstil MÜSSEN revisionsbewusste Helfer-Commits verwenden. Handschreiben Sie KEINE
file-state-Markierungen. STORAGE_ROOT/state.jsonundSTORAGE_ROOT/config.jsonDÜRFEN während des normalen Betriebs NICHT von Hand bearbeitet werden.- Protokoll
1.0tägliche Log-Zähler sind dateilokal:entry-seqist1..Ninnerhalb eines täglichen Logs und die kanonischeentry-idistentry-{entry_seq}. Behandeln Sie KEINE von beiden als global eindeutig. - Behalten Sie
state.json.daily_logs.entry_countalsentry_count; es bedeutet die Anzahl der Eintragsmarkierungen im neuesten aktiven täglichen Log, keine globale kumulative Anzahl. - Wenn ein Helfer-Schreibvorgang fehlschlägt, diagnostizieren, reparieren, wiederholen, dann den Helfer-Fehlervertrag ausgeben, wenn er immer noch nicht abgeschlossen werden kann.
- Die Wiederherstellung eines beschädigten Sidecars MUSS die kanonischen Wiederherstellungsvorschlags-/Überprüfungs-/Förderungshelfer und
validate_context.pyverwenden; bearbeiten Sie NICHT von Hand verwaltete Markierungen,state.json,config.json, Empfänge oder Helfer-Beweisspeicher.
Wann man es verwendet
Verwenden Sie RecallLoom, wenn Sie:
- ein bestehendes Projekt nach einer Pause fortsetzen möchten
- den Projektkontext aus gepflegten Dateien wiederherstellen möchten
- den aktuellen Zustand des Projektspeichers erhalten möchten
- sinnvolle Meilensteinfortschritte aufzeichnen möchten
- die Kontextdrift über Sitzungen oder Werkzeuge hinweg reduzieren möchten
Typische Auslöser sind:
- dieses Projekt fortsetzen
- Projektkontext wiederherstellen
- dort weitermachen, wo wir aufgehört haben
- rl-init
- den Projektspeicher aktualisieren
- den heutigen Fortschritt aufzeichnen
- eine saubere Übergabe der nächsten Schritte in den gepflegten Projektdateien vorbereiten
Erstes Anhängeverhalten
Beim ersten expliziten Aufruf in einem Projekt sollte RecallLoom nicht davon ausgehen, dass der Workspace bereits initialisiert ist.
Der korrekte Ablauf ist:
- erkennen, ob bereits ein gültiger RecallLoom-Sidecar existiert
- wenn er existiert, normal fortsetzen, ohne die Initialisierung zu einer zusätzlichen Zeremonie zu machen
- wenn er nicht existiert, erklären, dass das Projekt noch nicht initialisiert ist, und fragen, ob die Initialisierung durchgeführt werden soll
- wenn der Benutzer explizit zustimmt oder direkt
rl-initsagt, die standardmäßige Initialisierungsaktion ausführen - wenn die Umgebung kein Python
3.10+bereitstellen kann, mit einem blockierten Laufzeitergebnis stoppen, anstatt einen Sidecar von Hand zu bauen
rl-init SOLLTE bedeuten: den Sidecar initialisieren, den Workspace validieren und die nächsten empfohlenen Aktionen zurückgeben. Behandeln Sie es als stabilen High-Level-Aktionsnamen, auch wenn der Host keine nativen Slash-Befehle bereitstellt.
Aktuelle Aktionsoberfläche
Für die aktuelle Paketlinie sind die stabilen bedienerorientierten Wrapper-Ziele:
rl-initrl-resumerl-statusrl-validate
rl-init ist der primäre bedienerfreundliche Aktionsname für den ersten Anhang.
Die anderen sind stabile, bedienerorientierte Aktionsnamen, die vom Host-Agenten interpretiert oder in native benutzerdefinierte Befehle abgebildet werden können, wenn der Host diese Oberfläche unterstützt.
rl-bridge bleibt die kanonische Dispatcher-/Helfer-Aktionsbezeichnung für Brückenarbeit, aber diese Paketlinie verspricht keinen universellen nativen Wrapper oder deterministisches First-Hop-Routing für diese Bezeichnung.
Natürliche Sprache bleibt die standardmäßige öffentliche Formulierung für diese Aktionen.
Die Dispatcher-Befehlsoberfläche umfasst auch quick-summary, record --plan, append, write, sync-current-state-after-append und repair-daily-log-cursor.
Verwenden Sie quick-summary für aktuelle Zustands-Snapshots, record --plan zum Klassifizieren einer Aufnahmeabsicht und zum Erhalten des nächsten sicheren Helferschritts, append --entry-json für Meilenstein-Logging, write --type ... --source-file <vorbereitete-datei> --dry-run oder write --type ... --stdin --dry-run vor getippten verwalteten Dateischreibvorgängen und sync-current-state-after-append --reuse-current-summary --semantic-unchanged-assertion-json <json> nur nach Preflight-Überprüfung, die post_append_summary_sync nur für Metadaten erlaubt; siehe references/recording-workflow.md für das gebundene Assertions-JSON-Skelett.
Verwenden Sie repair-daily-log-cursor zuerst im Vorschaumodus, wenn state.json.daily_logs nicht mehr mit dem geparsten neuesten aktiven täglichen Log übereinstimmt. Der Anwendungsmodus erfordert --apply --yes, sollte --expected-workspace-revision nach einer frischen Vorschau-/Statusprüfung enthalten, ist als mutierend support-gestützt und repariert Cursor-Felder, ohne Helfer-Empfänge zu schreiben oder tägliche Log-Inhalte neu zu schreiben.
Diese Dispatcher-Ergänzungen sind optional für bestehende v0.3.4-Projekte und ändern das Sidecar-Protokoll 1.0 nicht.
Native Wrapper für rl-init, rl-resume, rl-status und rl-validate
sind nur Komfort-Einstiegspunkte. Sie müssen an denselben Dispatcher delegieren und
DÜRFEN natürliche Sprachwiederherstellungsanfragen nicht ersetzen, Helfer umgehen oder eine hostspezifische Produktlogikkopie erstellen.
Wiederherstellungsvertrag für initialisierte Projekte
Wenn ein Host oder Agent eine generische Wiederherstellungsanforderung für ein initialisiertes Projekt sieht:
- vor dem breiten Skill-Fan-out nach einem gültigen RecallLoom-Sidecar suchen
- wenn der Sidecar gültig ist, in den normalen RecallLoom-Schnellpfad leiten
- breitere Speicher- oder Workflow-Systeme nur dann teilnehmen lassen, wenn der Sidecar fehlt, widersprüchlich, eindeutig unzureichend ist oder der Benutzer explizit um eine tiefergehende Überprüfung bittet
Für die aktuelle Paketlinie ist rl-resume der einzige stabile bedienerorientierte Aktionsname für diesen Wiederherstellungs-Checkpoint initialisierter Projekte.
Wiederherstellungsanfragen in natürlicher Sprache bleiben der primäre öffentliche Pfad.
Erfinden Sie KEINEN manuellen Sidecar-Fallback oder einen hostlokalen Wiederherstellungs-Alias, der nicht durch den Paketvertrag gedeckt ist.
Öffentliche Interaktionsregeln
RecallLoom sollte standardmäßig die Sprache der Benutzeraufgabe verwenden, nicht die Implementierungssprache.
- Bevorzugen Sie "initialisieren", "wiederherstellen", "bestehende Projektrealität importieren", "fortsetzen" und "Fortschritt aufzeichnen".
- Führen Sie NICHT mit Helfernamen, Abschnittsschlüsseln oder dem
coldstart-Label, es sei denn, der Benutzer führt explizit Bediener-/Debug-Arbeiten durch. - Halten Sie die erste Antwort ergebnisorientiert und aktionsarm: Ein klarer nächster Schritt ist besser als die Offenlegung von Routing-Details.
- Erfinden Sie KEINEN manuellen Sidecar-Fallback, wenn Laufzeitanforderungen fehlen; zeigen Sie den blockierten Zustand an und stoppen Sie.
- Dies ist kein Handbau eines Sidecars; es ist der paketierte Wiederherstellungs- und Helfervertrag.
Schnelle und tiefe Pfade
RecallLoom sollte den schnellen Pfad als Standard-Interaktionsmodus behandeln.
- Schneller Pfad: kleinster vertrauenswürdiger Quellsatz, kürzeste Interaktion, niedrigste Unterbrechungskosten.
- Tiefer Pfad: nur wenn Quellen in Konflikt stehen, die Quellenabdeckung unzureichend ist, das Risiko für eine direkte Empfehlung zu hoch ist oder der Benutzer explizit um eine tiefergehende Überprüfung bittet.
- Hostspeicher-Eingaben bleiben opt-in und hinweisartig; ihre Anwesenheit sollte den Agenten zur expliziten Überprüfung anstatt zur stillen Übernahme bewegen.
Auswahl des Wiederaufnahmemodus:
- Verwenden Sie den normalen
resumeoderstatus, wenn der nächste Agent die übliche gestufte Leseplan-Anleitung benötigt, bevor er entscheidet, was gelesen werden soll. - Verwenden Sie
resume --fast, wenn die aktuelle Zustandsorientierung ausreicht und der nächste sichere Schritt ausstate.jsonplusrolling_summary.mdausgewählt werden kann. - Verwenden Sie
resume --full, wenn stabile Rahmenbedingungen, Source-of-Truth-Routing oder projektlokaleupdate_protocol.md-Anleitung vor der Aktion benötigt werden. - Halten Sie tägliche Log-Beweise bei Bedarf über
query_continuity.pyverfügbar; die schnellen und vollständigen Wiederaufnahmemodi sollten sich standardmäßig nicht in tägliche Logs ausdehnen.
Kern-Dateimodell
RecallLoom verwendet drei primäre Speicherschichten:
STORAGE_ROOT/context_brief.md: stabile ProjektrahmenSTORAGE_ROOT/rolling_summary.md: aktueller Zustands-Snapshot im ÜberschreibstilSTORAGE_ROOT/daily_logs/YYYY-MM-DD.md: meilensteinbasierte Beweise im AnhängestilSTORAGE_ROOT/config.json: maschinenlesbare Workspace-EinstellungenSTORAGE_ROOT/state.json: maschinenlesbarer Sidecar-Zustand für nebenläufigkeitsbewusste HelferSTORAGE_ROOT/update_protocol.md: empfohlene projektlokale Überschichtungsebene für Lese- und Schreibverhalten
Dateiverantwortlichkeiten in einem Satz:
context_brief.mderklärt, was dieses Projekt ist und wie es angegangen werden sollte.rolling_summary.mderklärt, was gerade wahr ist.daily_logs/erklären, was auf Meilensteinebene passiert ist.config.jsonhält Speicher- und Spracheinstellungen stabil.state.jsonverfolgt die Workspace-Revision und den helfer-sichtbaren Sidecar-Zustand.update_protocol.md, falls vorhanden, kann die standardmäßigen Lese-/Schreibregeln für dieses spezifische Projekt einschränken oder verschärfen.
STORAGE_ROOT ist entweder PROJECT_ROOT/.recallloom/ oder PROJECT_ROOT/recallloom/. Es DARF genau einen gültigen Speicherstamm geben; wenn beide existieren, anstatt zu raten, anhalten.
Maschinenlesbare Markierungen, nicht Überschriftenlabel, sind der normative Dateivertrag. Protokoll 1.0 unterstützt die Workspace-Sprachen en und zh-CN. Siehe references/file-contracts.md.
Minimaler Kaltstartablauf
- Das Projektstammverzeichnis finden.
STORAGE_ROOT/config.jsonlesen.STORAGE_ROOT/state.jsonlesen.STORAGE_ROOT/rolling_summary.mdlesen.- Wenn
STORAGE_ROOT/update_protocol.mdvorhanden ist, es für projektspezifische Regeln lesen. - Wenn ein Wiederherstellungsanforderung vorliegt,
context_brief.mdzur Rahmengebung lesen. - Wenn eine tägliche Log-Abfrage vorliegt, die entsprechende(n) tägliche(n) Log(s) lesen.
Unterstützte Sprachen
- Englisch (
en) - Chinesisch (vereinfacht,
zh-CN)
Lizenz
Siehe LICENSE.