Active Memory to opcjonalny, należący do Plugin, blokujący podagent pamięci, który działa przed główną odpowiedzią w kwalifikujących się sesjach konwersacyjnych. Istnieje dlatego, że większość systemów pamięci jest zaawansowana, ale reaktywna. Polegają one na tym, że główny agent zdecyduje, kiedy przeszukać pamięć, albo że użytkownik powie rzeczy takie jak „zapamiętaj to” lub „przeszukaj pamięć”. Wtedy moment, w którym pamięć sprawiłaby, że odpowiedź brzmiałaby naturalnie, już minął. Active Memory daje systemowi jedną ograniczoną szansę na wydobycie istotnej pamięci zanim zostanie wygenerowana główna odpowiedź.Documentation Index
Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt
Use this file to discover all available pages before exploring further.
Szybki start
Wklej to doopenclaw.json, aby uzyskać bezpieczną konfigurację domyślną — Plugin włączony, ograniczony do
agenta main, tylko sesje wiadomości bezpośrednich, dziedziczy model sesji,
gdy jest dostępny:
plugins.entries.active-memory.enabled: truewłącza Pluginconfig.agents: ["main"]włącza Active Memory tylko dla agentamainconfig.allowedChatTypes: ["direct"]ogranicza ją do sesji wiadomości bezpośrednich (grupy/kanały włączaj jawnie)config.model(opcjonalnie) przypina dedykowany model przywoływania; brak ustawienia dziedziczy bieżący model sesjiconfig.modelFallbackjest używany tylko wtedy, gdy nie zostanie rozpoznany model jawny ani dziedziczonyconfig.promptStyle: "balanced"jest wartością domyślną dla tryburecent- Active Memory nadal działa tylko dla kwalifikujących się interaktywnych trwałych sesji czatu
Zalecenia dotyczące szybkości
Najprostsza konfiguracja to pozostawienieconfig.model bez ustawienia i pozwolenie Active Memory używać
tego samego modelu, którego używasz już do zwykłych odpowiedzi. To najbezpieczniejsza wartość domyślna,
ponieważ podąża za istniejącymi preferencjami dostawcy, uwierzytelniania i modelu.
Jeśli chcesz, aby Active Memory działała szybciej, użyj dedykowanego modelu inferencyjnego
zamiast pożyczać główny model czatu. Jakość przywoływania ma znaczenie, ale opóźnienie
ma większe znaczenie niż w głównej ścieżce odpowiedzi, a powierzchnia narzędzi Active Memory
jest wąska (wywołuje tylko dostępne narzędzia przywoływania pamięci).
Dobre opcje szybkich modeli:
cerebras/gpt-oss-120bjako dedykowany model przywoływania o niskim opóźnieniugoogle/gemini-3-flashjako zapasowy model o niskim opóźnieniu bez zmieniania głównego modelu czatu- twój zwykły model sesji, przez pozostawienie
config.modelbez ustawienia
Konfiguracja Cerebras
Dodaj dostawcę Cerebras i skieruj na niego Active Memory:chat/completions dla
wybranego modelu — sama widoczność w /v1/models tego nie gwarantuje.
Jak to zobaczyć
Active Memory wstrzykuje ukryty, niezaufany prefiks promptu dla modelu. Nie ujawnia surowych znaczników<active_memory_plugin>...</active_memory_plugin> w
normalnej odpowiedzi widocznej dla klienta.
Przełącznik sesji
Użyj polecenia Plugin, gdy chcesz wstrzymać lub wznowić Active Memory dla bieżącej sesji czatu bez edytowania konfiguracji:plugins.entries.active-memory.enabled, wyboru agentów ani innej globalnej
konfiguracji.
Jeśli chcesz, aby polecenie zapisało konfigurację i wstrzymało lub wznowiło Active Memory dla
wszystkich sesji, użyj jawnej formy globalnej:
plugins.entries.active-memory.config.enabled. Pozostawia
plugins.entries.active-memory.enabled włączone, aby polecenie pozostało dostępne do
ponownego włączenia Active Memory później.
Jeśli chcesz zobaczyć, co Active Memory robi w sesji na żywo, włącz
przełączniki sesji odpowiadające oczekiwanemu wyjściu:
- wiersz statusu Active Memory, taki jak
Active Memory: status=ok elapsed=842ms query=recent summary=34 chars, gdy/verbose on - czytelne podsumowanie debugowania, takie jak
Active Memory Debug: Lemon pepper wings with blue cheese., gdy/trace on
/trace raw, śledzony blok Model Input (User Role) pokaże
ukryty prefiks Active Memory jako:
Kiedy działa
Active Memory używa dwóch bramek:- Jawne włączenie w konfiguracji
Plugin musi być włączony, a identyfikator bieżącego agenta musi występować w
plugins.entries.active-memory.config.agents. - Ścisła kwalifikowalność w czasie wykonywania Nawet gdy jest włączona i skierowana do agenta, Active Memory działa tylko w kwalifikujących się interaktywnych trwałych sesjach czatu.
Typy sesji
config.allowedChatTypes kontroluje, w jakich rodzajach rozmów Active Memory może w ogóle działać.
Wartość domyślna to:
config.allowedChatIds i
config.deniedChatIds po wybraniu dozwolonych typów sesji.
allowedChatIds to jawna lista dozwolonych rozpoznanych identyfikatorów rozmów. Gdy
nie jest pusta, Active Memory działa tylko wtedy, gdy identyfikator rozmowy sesji znajduje się na
tej liście. Zawęża to wszystkie dozwolone typy czatu naraz, w tym wiadomości bezpośrednie.
Jeśli chcesz wszystkie wiadomości bezpośrednie plus tylko określone grupy, uwzględnij
identyfikatory bezpośrednich rozmówców w allowedChatIds albo pozostaw allowedChatTypes skupione na
wdrożeniu grup/kanałów, które testujesz.
deniedChatIds to jawna lista odmów. Zawsze ma pierwszeństwo przed
allowedChatTypes i allowedChatIds, więc pasująca rozmowa jest pomijana
nawet wtedy, gdy jej typ sesji jest poza tym dozwolony.
Identyfikatory pochodzą z trwałego klucza sesji kanału: na przykład Feishu
chat_id / open_id, identyfikator czatu Telegram albo identyfikator kanału Slack. Dopasowanie jest
niewrażliwe na wielkość liter. Jeśli allowedChatIds nie jest puste, a OpenClaw nie może rozpoznać
identyfikatora rozmowy dla sesji, Active Memory pomija turę zamiast
zgadywać.
Przykład:
Gdzie działa
Active Memory to funkcja wzbogacania konwersacji, a nie ogólnoplatformowa funkcja inferencji.| Powierzchnia | Czy uruchamia Active Memory? |
|---|---|
| Control UI / trwałe sesje czatu WWW | Tak, jeśli Plugin jest włączony, a agent jest wskazany |
| Inne interaktywne sesje kanałów na tej samej trwałej ścieżce czatu | Tak, jeśli Plugin jest włączony, a agent jest wskazany |
| Bezinterfejsowe jednorazowe przebiegi | Nie |
| Heartbeat/przebiegi w tle | Nie |
Ogólne wewnętrzne ścieżki agent-command | Nie |
| Wykonywanie podagentów/wewnętrznych pomocników | Nie |
Dlaczego jej używać
Używaj Active Memory, gdy:- sesja jest trwała i widoczna dla użytkownika
- agent ma sensowną pamięć długoterminową do przeszukania
- ciągłość i personalizacja są ważniejsze niż surowy determinizm promptu
- stabilnych preferencji
- powtarzających się nawyków
- długoterminowego kontekstu użytkownika, który powinien pojawiać się naturalnie
- automatyzacji
- wewnętrznych workerów
- jednorazowych zadań API
- miejsc, w których ukryta personalizacja byłaby zaskakująca
Jak to działa
Kształt działania w czasie wykonywania to: Blokujący podagent pamięci może używać tylko skonfigurowanych narzędzi przywoływania pamięci. Domyślnie są to:memory_searchmemory_get
plugins.slots.memory ma wartość memory-lancedb, domyślnie używane jest zamiast tego memory_recall.
Ustaw config.toolsAllow, gdy inny dostawca pamięci udostępnia inny kontrakt narzędzia
przywoływania.
Jeśli połączenie jest słabe, powinien zwrócić NONE.
Tryby zapytań
config.queryMode kontroluje, jak dużo rozmowy widzi blokujący podagent pamięci.
Wybierz najmniejszy tryb, który nadal dobrze odpowiada na pytania uzupełniające;
budżety limitu czasu powinny rosnąć wraz z rozmiarem kontekstu (message < recent < full).
- message
- recent
- full
Wysyłana jest tylko najnowsza wiadomość użytkownika.Użyj tego, gdy:
- chcesz najszybszego zachowania
- chcesz najsilniejszego ukierunkowania na przywoływanie stabilnych preferencji
- kolejne tury nie potrzebują kontekstu konwersacji
3000 do 5000 ms dla config.timeoutMs.Style promptów
config.promptStyle steruje tym, jak skłonny lub rygorystyczny jest blokujący subagent pamięci
przy decydowaniu, czy zwrócić pamięć.
Dostępne style:
balanced: domyślny styl ogólnego przeznaczenia dla tryburecentstrict: najmniej skłonny; najlepszy, gdy chcesz bardzo mało przenikania z pobliskiego kontekstucontextual: najbardziej sprzyja ciągłości; najlepszy, gdy historia rozmowy powinna mieć większe znaczenierecall-heavy: chętniej ujawnia pamięć przy słabszych, ale nadal wiarygodnych dopasowaniachprecision-heavy: agresywnie preferujeNONE, chyba że dopasowanie jest oczywistepreference-only: zoptymalizowany pod ulubione rzeczy, nawyki, rutyny, gust i powtarzające się fakty osobiste
config.promptStyle nie jest ustawione:
config.promptStyle jawnie, to nadpisanie ma pierwszeństwo.
Przykład:
Zasady awaryjnego wyboru modelu
Jeśliconfig.model nie jest ustawione, Active Memory próbuje rozwiązać model w tej kolejności:
config.modelFallback steruje skonfigurowanym krokiem awaryjnym.
Opcjonalny niestandardowy model awaryjny:
config.modelFallbackPolicy jest zachowane tylko jako przestarzałe pole
zgodności dla starszych konfiguracji. Nie zmienia już zachowania w czasie wykonywania.
Narzędzia pamięci
Domyślnie Active Memory pozwala blokującemu subagentowi przywoływania wywoływaćmemory_search i memory_get. Jest to zgodne z wbudowanym kontraktem memory-core.
Gdy plugins.slots.memory wybiera memory-lancedb, a config.toolsAllow
nie jest ustawione, Active Memory zachowuje istniejące zachowanie LanceDB
i używa zamiast tego memory_recall.
Jeśli używasz innego Plugin pamięci, ustaw config.toolsAllow na dokładne nazwy
narzędzi rejestrowane przez ten Plugin. Active Memory wymienia te narzędzia w prompcie
przywoływania i przekazuje tę samą listę do osadzonego subagenta. Jeśli żadne ze
skonfigurowanych narzędzi nie jest dostępne albo subagent pamięci zawiedzie, Active Memory
pomija przywoływanie dla tej tury, a główna odpowiedź jest kontynuowana bez kontekstu z pamięci.
toolsAllow przyjmuje tylko konkretne nazwy narzędzi pamięci. Symbole wieloznaczne, wpisy
group:* oraz podstawowe narzędzia agenta, takie jak read, exec, message i
web_search, są ignorowane przed uruchomieniem ukrytego subagenta pamięci.
Uwaga o zachowaniu domyślnym: Active Memory nie uwzględnia już memory_recall w domyślnej
liście dozwolonych narzędzi memory-core. Istniejące konfiguracje memory-lancedb nadal działają,
gdy plugins.slots.memory jest ustawione na memory-lancedb. Jawne toolsAllow
zawsze nadpisuje automatyczną wartość domyślną.
Wbudowane memory-core
Domyślna konfiguracja nie wymaga jawnegotoolsAllow:
Pamięć LanceDB
Dołączony Pluginmemory-lancedb udostępnia memory_recall. Wybranie
slotu pamięci wystarczy, aby Active Memory używało tego narzędzia przywoływania:
Lossless Claw
Lossless Claw to Plugin silnika kontekstu z własnymi narzędziami przywoływania. Najpierw zainstaluj i skonfiguruj go jako silnik kontekstu; zobacz Silnik kontekstu. Następnie pozwól Active Memory używać narzędzi przywoływania Lossless Claw:lcm_expand w toolsAllow dla głównego subagenta Active Memory.
Lossless Claw używa go jako delegowanego narzędzia rozszerzania niższego poziomu.
Zaawansowane wyjścia awaryjne
Te opcje celowo nie są częścią zalecanej konfiguracji.config.thinking może nadpisać poziom myślenia blokującego subagenta pamięci:
config.promptAppend dodaje dodatkowe instrukcje operatora po domyślnym prompcie Active
Memory i przed kontekstem rozmowy:
promptAppend z niestandardowym toolsAllow, gdy Plugin pamięci spoza core
wymaga instrukcji specyficznych dla dostawcy dotyczących kolejności narzędzi lub kształtowania zapytań.
config.promptOverride zastępuje domyślny prompt Active Memory. OpenClaw
nadal dołącza potem kontekst rozmowy:
NONE,
albo zwięzły kontekst faktów o użytkowniku dla głównego modelu.
Utrwalanie transkrypcji
Uruchomienia blokującego subagenta pamięci Active Memory tworzą rzeczywistą transkrypcjęsession.jsonl podczas wywołania blokującego subagenta pamięci.
Domyślnie ta transkrypcja jest tymczasowa:
- jest zapisywana w katalogu tymczasowym
- jest używana tylko podczas uruchomienia blokującego subagenta pamięci
- jest usuwana natychmiast po zakończeniu uruchomienia
config.transcriptDir.
Używaj tego ostrożnie:
- transkrypcje blokującego subagenta pamięci mogą szybko gromadzić się w aktywnych sesjach
- tryb zapytań
fullmoże powielać dużo kontekstu rozmowy - te transkrypcje zawierają ukryty kontekst promptu i przywołane wspomnienia
Konfiguracja
Cała konfiguracja active memory znajduje się pod:| Klucz | Typ | Znaczenie |
|---|---|---|
enabled | boolean | Włącza sam Plugin |
config.agents | string[] | Identyfikatory agentów, które mogą używać aktywnej pamięci |
config.model | string | Opcjonalny ref modelu blokującego subagenta pamięci; gdy nie jest ustawiony, aktywna pamięć używa modelu bieżącej sesji |
config.allowedChatTypes | ("direct" | "group" | "channel")[] | Typy sesji, które mogą uruchamiać Active Memory; domyślnie są to sesje w stylu wiadomości bezpośrednich |
config.allowedChatIds | string[] | Opcjonalna lista dozwolonych rozmów stosowana po allowedChatTypes; niepuste listy domyślnie blokują wszystko poza wpisami z listy |
config.deniedChatIds | string[] | Opcjonalna lista zablokowanych rozmów, która zastępuje dozwolone typy sesji i dozwolone identyfikatory |
config.queryMode | "message" | "recent" | "full" | Kontroluje, jak dużą część rozmowy widzi blokujący subagent pamięci |
config.promptStyle | "balanced" | "strict" | "contextual" | "recall-heavy" | "precision-heavy" | "preference-only" | Kontroluje, jak chętny lub rygorystyczny jest blokujący subagent pamięci przy decydowaniu, czy zwrócić pamięć |
config.toolsAllow | string[] | Konkretne nazwy narzędzi pamięci, które może wywoływać blokujący subagent pamięci; domyślnie ["memory_search", "memory_get"] albo ["memory_recall"], gdy plugins.slots.memory to memory-lancedb; symbole wieloznaczne, wpisy group:* i narzędzia agenta rdzenia są ignorowane |
config.thinking | "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "adaptive" | "max" | Zaawansowane zastąpienie myślenia dla blokującego subagenta pamięci; domyślnie off dla szybkości |
config.promptOverride | string | Zaawansowana pełna zamiana promptu; niezalecana do normalnego użycia |
config.promptAppend | string | Zaawansowane dodatkowe instrukcje dołączane do domyślnego lub zastąpionego promptu |
config.timeoutMs | number | Twardy limit czasu dla blokującego subagenta pamięci, ograniczony do 120000 ms |
config.setupGraceTimeoutMs | number | Zaawansowany dodatkowy budżet konfiguracji przed wygaśnięciem limitu czasu przywołania; domyślnie 0 i ograniczony do 30000 ms. Zobacz bufor zimnego startu, aby uzyskać wskazówki dotyczące aktualizacji v2026.4.x |
config.maxSummaryChars | number | Maksymalna łączna liczba znaków dozwolona w podsumowaniu aktywnej pamięci |
config.logging | boolean | Emituje dzienniki aktywnej pamięci podczas strojenia |
config.persistTranscripts | boolean | Zachowuje transkrypty blokującego subagenta pamięci na dysku zamiast usuwać pliki tymczasowe |
config.transcriptDir | string | Względny katalog transkryptów blokującego subagenta pamięci pod folderem sesji agenta |
| Klucz | Typ | Znaczenie |
|---|---|---|
config.maxSummaryChars | number | Maksymalna łączna liczba znaków dozwolona w podsumowaniu aktywnej pamięci |
config.recentUserTurns | number | Poprzednie tury użytkownika do uwzględnienia, gdy queryMode to recent |
config.recentAssistantTurns | number | Poprzednie tury asystenta do uwzględnienia, gdy queryMode to recent |
config.recentUserChars | number | Maksymalna liczba znaków na ostatnią turę użytkownika |
config.recentAssistantChars | number | Maksymalna liczba znaków na ostatnią turę asystenta |
config.cacheTtlMs | number | Ponowne użycie pamięci podręcznej dla powtarzanych identycznych zapytań (zakres: 1000-120000 ms; domyślnie: 15000) |
config.circuitBreakerMaxTimeouts | number | Pomija przywołanie po tylu kolejnych przekroczeniach limitu czasu dla tego samego agenta/modelu. Resetuje się po udanym przywołaniu albo po upływie czasu odnowienia (zakres: 1-20; domyślnie: 3). |
config.circuitBreakerCooldownMs | number | Jak długo pomijać przywołanie po zadziałaniu wyłącznika awaryjnego, w ms (zakres: 5000-600000; domyślnie: 60000). |
Zalecana konfiguracja
Zacznij odrecent.
/verbose on
dla zwykłego wiersza statusu i /trace on dla podsumowania debugowania
active-memory zamiast szukać oddzielnego polecenia debugowania active-memory.
W kanałach czatu te wiersze diagnostyczne są wysyłane po głównej odpowiedzi
asystenta, a nie przed nią.
Następnie przejdź do:
message, jeśli chcesz mniejszego opóźnieniafull, jeśli uznasz, że dodatkowy kontekst jest wart wolniejszego blokującego subagenta pamięci
Bufor zimnego startu
Przed v2026.5.2 Plugin po cichu wydłużał skonfigurowanetimeoutMs o
dodatkowe 30000 ms podczas zimnego startu, aby rozgrzewanie modelu,
ładowanie indeksu osadzeń i pierwsze przywołanie mogły współdzielić jeden
większy budżet. v2026.5.2 przeniosła ten bufor za jawną konfigurację
setupGraceTimeoutMs — skonfigurowane timeoutMs jest teraz domyślnym
budżetem, chyba że świadomie go rozszerzysz.
Jeśli zaktualizowano z v2026.4.x i ustawiono timeoutMs na wartość dostrojoną
do starego świata niejawnego bufora (zalecane początkowe timeoutMs: 15000
jest jednym z przykładów), ustaw setupGraceTimeoutMs: 30000, aby rozszerzyć
budżety hooka budowania promptu i zewnętrznego watchdoga z powrotem do
efektywnych wartości sprzed v5.2:
setupGraceTimeoutMs,
dzięki czemu Plugin nie wydłuża już po cichu konfiguracji 15000 ms do 45000 ms
w głównej ścieżce.”
Wbudowany runner przywoływania używa tego samego efektywnego budżetu limitu czasu, więc
setupGraceTimeoutMs obejmuje zarówno zewnętrzny watchdog budowania promptu, jak i wewnętrzne
blokujące uruchomienie przywoływania.
W przypadku Gateway z ograniczonymi zasobami, gdzie opóźnienie zimnego startu jest znanym kompromisem,
niższe wartości (5000–15000 ms) również działają — kompromisem jest większe ryzyko,
że pierwsze przywoływanie po restarcie Gateway zwróci pusty wynik, zanim rozgrzewanie
dobiegnie końca.
Debugowanie
Jeśli Active Memory nie pojawia się tam, gdzie oczekujesz:- Potwierdź, że Plugin jest włączony w
plugins.entries.active-memory.enabled. - Potwierdź, że bieżący identyfikator agenta znajduje się na liście
config.agents. - Potwierdź, że testujesz przez interaktywną, trwałą sesję czatu.
- Włącz
config.logging: truei obserwuj logi Gateway. - Zweryfikuj, że samo wyszukiwanie pamięci działa za pomocą
openclaw memory status --deep.
maxSummaryChars
- obniż
queryMode - obniż
timeoutMs - zmniejsz liczbę ostatnich tur
- zmniejsz limity znaków na turę
Częste problemy
Active Memory opiera się na potoku przywoływania skonfigurowanego Plugin pamięci, więc większość niespodzianek z przywoływaniem to problemy z dostawcą embeddingów, a nie błędy Active Memory. Domyślna ścieżkamemory-core używa memory_search i memory_get; slot
memory-lancedb używa memory_recall. Jeśli używasz innego Plugin pamięci,
potwierdź, że config.toolsAllow nazywa narzędzia, które ten Plugin faktycznie rejestruje.
Dostawca embeddingów został przełączony lub przestał działać
Dostawca embeddingów został przełączony lub przestał działać
Jeśli
memorySearch.provider nie jest ustawione, OpenClaw automatycznie wykrywa pierwszego
dostępnego dostawcę embeddingów. Nowy klucz API, wyczerpanie limitu lub
limitowany szybkościowo dostawca hostowany może zmienić to, który dostawca zostanie rozpoznany między
uruchomieniami. Jeśli żaden dostawca nie zostanie rozpoznany, memory_search może zostać zdegradowane do pobierania
wyłącznie leksykalnego; awarie w czasie działania po wybraniu dostawcy nie
przełączają się automatycznie na rozwiązanie zapasowe.Przypnij dostawcę (oraz opcjonalne rozwiązanie zapasowe) jawnie, aby wybór był
deterministyczny. Zobacz Memory Search, aby uzyskać pełną
listę dostawców i przykłady przypinania.Przywoływanie wydaje się wolne, puste lub niespójne
Przywoływanie wydaje się wolne, puste lub niespójne
- Włącz
/trace on, aby wyświetlić w sesji podsumowanie debugowania Active Memory należące do Plugin. - Włącz
/verbose on, aby dodatkowo widzieć wiersz statusu🧩 Active Memory: ...po każdej odpowiedzi. - Obserwuj logi Gateway pod kątem
active-memory: ... start|done,memory sync failed (search-bootstrap)lub błędów embeddingów dostawcy. - Uruchom
openclaw memory status --deep, aby sprawdzić backend wyszukiwania pamięci i stan indeksu. - Jeśli używasz
ollama, potwierdź, że model embeddingów jest zainstalowany (ollama list).
Pierwsze przywołanie po restarcie Gateway zwraca `status=timeout`
Pierwsze przywołanie po restarcie Gateway zwraca `status=timeout`
W v2026.5.2 i nowszych, jeśli konfiguracja zimnego startu (rozgrzewanie modelu + ładowanie
indeksu embeddingów) nie zakończyła się do czasu uruchomienia pierwszego przywoływania, przebieg
może osiągnąć skonfigurowany budżet
timeoutMs i zwrócić status=timeout
z pustym wynikiem. Logi Gateway pokazują active-memory timeout after Nms
w okolicy pierwszej kwalifikującej się odpowiedzi po restarcie.Zobacz Czas karencji zimnego startu w sekcji Zalecana konfiguracja, aby poznać
zalecaną wartość setupGraceTimeoutMs.