OpenClaw Active Memory 설정: 5분 만에 지능형 기억 기능 활성화

Active Memory

Active Memory는 대화 세션에서 메인 답변이 생성되기 전에 실행되는 선택 사항인 플러그인 소유 차단형 메모리 sub-agent예요.

대부분의 메모리 시스템은 기능은 뛰어나지만 반응형이라는 한계가 있어요. 메인 에이전트가 메모리를 검색할 시점을 직접 결정하거나, 사용자가 “이걸 기억해 줘” 또는 “메모리에서 찾아봐”라고 말해야만 작동하거든요. 하지만 그 시점이 되면 이미 메모리를 활용해 자연스럽게 답변할 수 있는 타이밍을 놓치기 일쑤예요.

Active Memory는 메인 답변이 생성되기 전에 관련 메모리를 표면으로 끌어올릴 수 있는 제한된 기회를 시스템에 한 번 더 제공합니다.

에이전트에 이 코드를 붙여넣으세요

Active Memory를 설정이 다 되어 있는 안전한 기본 상태로 사용하고 싶다면, 에이전트에 이 설정을 붙여넣으세요.

{
  plugins: {
    entries: {
      "active-memory": {
        enabled: true,
        config: {
          enabled: true,
          agents: ["main"],
          allowedChatTypes: ["direct"],
          modelFallbackPolicy: "default-remote",
          queryMode: "recent",
          promptStyle: "balanced",
          timeoutMs: 15000,
          maxSummaryChars: 220,
          persistTranscripts: false,
          logging: true,
        },
      },
    },
  },
}

이 설정은 main 에이전트에서 플러그인을 활성화하고, 기본적으로 direct-message 스타일의 세션으로 제한해요. 현재 세션 모델을 먼저 상속받도록 하며, 명시적이거나 상속된 모델이 없을 때는 내장된 remote fallback을 사용하도록 설정되어 있어요.

그다음 Gateway를 재시작하세요.

openclaw gateway

대화 중에 실시간으로 확인하려면 이 명령어를 입력하세요.

/verbose on

Active Memory 활성화하기

가장 안전한 설정 방법은 다음과 같아요.

플러그인 활성화
하나의 대화형 에이전트를 타겟팅
튜닝하는 동안에만 로깅 유지

먼저 openclaw.json에 이 내용을 추가하세요.

{
  plugins: {
    entries: {
      "active-memory": {
        enabled: true,
        config: {
          agents: ["main"],
          allowedChatTypes: ["direct"],
          modelFallbackPolicy: "default-remote",
          queryMode: "recent",
          promptStyle: "balanced",
          timeoutMs: 15000,
          maxSummaryChars: 220,
          persistTranscripts: false,
          logging: true,
        },
      },
    },
  },
}

그다음 Gateway를 재시작하세요.

openclaw gateway

설정의 의미는 이렇습니다.

plugins.entries.active-memory.enabled: true는 플러그인을 켭니다.
config.agents: ["main"]은 main 에이전트만 Active Memory를 사용하도록 선택해요.
config.allowedChatTypes: ["direct"]는 기본적으로 direct-message 스타일의 세션에서만 Active Memory를 유지해요.
config.model이 설정되지 않으면, Active Memory는 현재 세션 모델을 먼저 상속받아요.
config.modelFallbackPolicy: "default-remote"는 사용할 수 있는 모델이 없을 때 내장된 remote fallback을 기본값으로 유지해요.
config.promptStyle: "balanced"는 recent 모드에 대해 기본 범용 프롬프트 스타일을 사용해요.
Active Memory는 여전히 조건에 맞는 인터랙티브한 지속형 채팅 세션에서만 실행됩니다.

작동 확인 방법

Active Memory는 모델을 위해 숨겨진 시스템 컨텍스트를 주입해요. 클라이언트에게 원본 <active_memory_plugin>...</active_memory_plugin> 태그를 그대로 노출하지는 않아요.

세션 토글

설정을 수정하지 않고 현재 채팅 세션에서 Active Memory를 일시 중지하거나 다시 시작하고 싶을 때는 플러그인 명령어를 사용하세요.

/active-memory status
/active-memory off
/active-memory on

이 명령어는 세션 범위에만 적용돼요. plugins.entries.active-memory.enabled나 에이전트 타겟팅, 기타 글로벌 설정은 변경하지 않아요.

만약 명령어를 통해 설정을 저장하고 모든 세션에서 Active Memory를 일시 중지하거나 재개하고 싶다면, 명시적인 글로벌 형식을 사용하세요.

/active-memory status --global
/active-memory off --global
/active-memory on --global

글로벌 형식은 plugins.entries.active-memory.config.enabled 값을 수정해요. 나중에 명령어로 Active Memory를 다시 켤 수 있도록 plugins.entries.active-memory.enabled는 켠 상태로 유지합니다.

실시간 세션에서 Active Memory가 무엇을 하고 있는지 보고 싶다면, 해당 세션에서 verbose 모드를 켜보세요.

/verbose on

verbose 모드가 활성화되면 OpenClaw는 다음 정보를 보여줄 수 있어요.

Active Memory: ok 842ms recent 34 chars와 같은 Active Memory 상태 라인
Active Memory Debug: Lemon pepper wings with blue cheese.와 같은 읽기 쉬운 디버그 요약

이 라인들은 숨겨진 시스템 컨텍스트에 입력되는 것과 동일한 Active Memory 패스에서 생성되지만, 원본 프롬프트 마크업 대신 사람이 읽기 좋은 형식으로 제공돼요.

기본적으로 이 차단형 메모리 sub-agent의 트랜스크립트는 임시적이며 실행이 완료되면 삭제됩니다.

실행 예시는 다음과 같아요.

/verbose on
what wings should i order?

예상되는 답변 형태는 이렇습니다.

...normal assistant reply...

🧩 Active Memory: ok 842ms recent 34 chars
🔎 Active Memory Debug: Lemon pepper wings with blue cheese.

실행 시점

Active memory는 두 가지 관문을 통과해야 작동해요.

설정 동의 (Config opt-in) 플러그인이 활성화되어야 하고, 현재 agent id가 plugins.entries.active-memory.config.agents에 포함되어 있어야 해요.
엄격한 런타임 적격성 (Strict runtime eligibility) 설정이 활성화되고 대상이 지정되었더라도, active memory는 적격한 대화형 persistent chat session에서만 실행돼요.

실제 규칙은 다음과 같아요:

plugin enabled
+
agent id targeted
+
allowed chat type
+
eligible interactive persistent chat session
=
active memory runs

이 조건 중 하나라도 충족되지 않으면 active memory는 실행되지 않아요.

세션 유형

config.allowedChatTypes는 어떤 종류의 대화에서 Active Memory를 실행할지 제어해요.

기본값은 다음과 같아요:

allowedChatTypes: ["direct"]

즉, Active Memory는 기본적으로 direct-message 스타일의 세션에서 실행돼요. group이나 channel 세션의 경우 명시적으로 설정을 추가해야만 작동해요.

설정 예시는 다음과 같아요:

allowedChatTypes: ["direct"]

allowedChatTypes: ["direct", "group"]

allowedChatTypes: ["direct", "group", "channel"]

실행 위치

Active memory는 대화 강화 기능이며, 플랫폼 전체에 적용되는 inference 기능이 아니에요.

Surface	Active memory 실행 여부
Control UI / web chat persistent sessions	예 (플러그인이 활성화되고 에이전트가 지정된 경우)
동일한 persistent chat 경로의 다른 대화형 channel sessions	예 (플러그인이 활성화되고 에이전트가 지정된 경우)
Headless one-shot 실행	아니요
Heartbeat/백그라운드 실행	아니요
일반적인 내부 `agent-command` 경로	아니요
Sub-agent/내부 헬퍼 실행	아니요

사용 이유

이런 상황일 때 active memory를 사용해 보세요:

세션이 지속적(persistent)이고 사용자를 직접 대면하며, 에이전트가 검색할 만한 의미 있는 장기 메모리를 가지고 있을 때
단순한 프롬프트 결정론보다 대화의 연속성과 개인화가 더 중요할 때

특히 다음과 같은 경우에 잘 어울려요:

사용자의 안정적인 선호도나 반복되는 습관을 파악할 때
자연스럽게 드러나야 하는 장기적인 사용자 컨텍스트가 필요할 때

반대로 이런 경우에는 적합하지 않아요:

자동화 작업
내부 워커(internal workers)
일회성(one-shot) API 작업
숨겨진 개인화 요소가 사용자에게 당혹감을 줄 수 있는 곳

작동 원리

런타임 구조는 다음과 같아요:

flowchart LR
  U["User Message"] --> Q["Build Memory Query"]
  Q --> R["Active Memory Blocking Memory Sub-Agent"]
  R -->|NONE or empty| M["Main Reply"]
  R -->|relevant summary| I["Append Hidden active_memory_plugin System Context"]
  I --> M["Main Reply"]

이 blocking memory sub-agent는 다음 기능만 사용할 수 있어요:

memory_search
memory_get

만약 연결 상태가 좋지 않다면 NONE을 반환해야 해요.

쿼리 모드 (Query modes)

config.queryMode는 blocking memory sub-agent가 전체 대화 내용 중 어느 정도를 살펴볼지 제어해요.

프롬프트 스타일 (Prompt styles)

config.promptStyle은 메모리를 반환할지 결정할 때 blocking memory sub-agent가 얼마나 적극적으로 혹은 엄격하게 판단할지를 제어해요.

사용 가능한 스타일은 다음과 같아요:

balanced: recent 모드에서 사용하는 일반적인 기본값이에요.
strict: 가장 덜 적극적이에요. 주변 컨텍스트의 영향을 최소화하고 싶을 때 적합해요.
contextual: 연속성을 가장 잘 유지해요. 대화 기록이 더 중요하게 작용해야 할 때 좋아요.
recall-heavy: 연관성이 조금 낮더라도 메모리를 더 적극적으로 찾아내요.
precision-heavy: 매칭이 확실하지 않으면 NONE을 반환하는 쪽을 선호해요.
preference-only: 취향, 습관, 루틴, 반복되는 개인적 사실에 최적화되어 있어요.

config.promptStyle이 설정되지 않았을 때의 기본 매핑은 다음과 같아요:

message -> strict
recent -> balanced
full -> contextual

만약 config.promptStyle을 직접 설정하면 해당 설정이 우선적으로 적용돼요.

예시:

promptStyle: "preference-only"

모델 폴백 정책 (Model fallback policy)

config.model이 설정되어 있지 않으면, Active Memory는 다음 순서에 따라 모델을 결정해요:

explicit plugin model
-> current session model
-> agent primary model
-> optional built-in remote fallback

config.modelFallbackPolicy는 이 과정의 마지막 단계를 제어해요.

기본값:

modelFallbackPolicy: "default-remote"

다른 옵션:

modelFallbackPolicy: "resolved-only"

명시적이거나 상속된 모델을 사용할 수 없을 때, 기본 원격 모델로 폴백하는 대신 메모리 회상 단계를 건너뛰고 싶다면 resolved-only를 사용하세요.

고급 탈출구 (Advanced escape hatches)

이 옵션들은 권장 설정에 포함되지 않는 기능들이에요.

config.thinking을 사용하면 blocking memory sub-agent의 thinking level을 직접 지정할 수 있어요.

thinking: "medium"

기본값은 다음과 같아요.

thinking: "off"

이 옵션을 기본으로 활성화하지는 마세요. Active Memory는 응답 경로에서 실행되기 때문에, 추가적인 thinking 시간은 사용자가 체감하는 latency를 직접적으로 높이게 됩니다.

config.promptAppend는 기본 Active Memory prompt 뒤와 conversation context 앞에 추가적인 operator 지침을 더해줘요.

promptAppend: "Prefer stable long-term preferences over one-off events."

config.promptOverride는 기본 Active Memory prompt를 아예 교체해요. OpenClaw는 그 뒤에 conversation context를 여전히 덧붙입니다.

promptOverride: "You are a memory search agent. Return NONE or one compact user fact."

다른 recall contract를 의도적으로 테스트하는 상황이 아니라면 prompt 커스텀은 추천하지 않아요. 기본 prompt는 메인 모델을 위해 NONE 또는 요약된 user-fact context를 반환하도록 최적화되어 있거든요.

`message`

가장 최근의 user message만 전송해요.

Latest user message only

이럴 때 사용하세요:

가장 빠른 동작을 원할 때
안정적인 preference recall에 강한 비중을 두고 싶을 때
후속 질문에 대화 맥락이 필요 없을 때

권장 timeout:

3000에서 5000 ms 사이로 시작해 보세요.

`recent`

최근 user message와 짧은 대화 기록을 함께 전송해요.

Recent conversation tail:
user: ...
assistant: ...
user: ...

Latest user message:
...

이럴 때 사용하세요:

속도와 대화 기반(grounding) 사이의 균형을 맞추고 싶을 때
후속 질문이 직전 몇 마디 대화에 의존하는 경우가 많을 때

권장 timeout:

약 15000 ms 정도로 시작해 보세요.

`full`

전체 대화 내용을 blocking memory sub-agent에게 전송해요.

Full conversation context:
user: ...
assistant: ...
user: ...
...

이럴 때 사용하세요:

latency보다 가장 강력한 recall 품질이 더 중요할 때
대화 내용 중 아주 앞부분에 중요한 설정이 포함되어 있을 때

권장 timeout:

message나 recent보다 훨씬 길게 설정하세요.
대화 크기에 따라 15000 ms 이상에서 시작하는 것이 좋습니다.

일반적으로 timeout은 context 크기에 따라 늘어나야 해요.

message < recent < full

Transcript persistence

Active memory의 blocking memory sub-agent가 실행될 때, 실제 session.jsonl transcript가 생성돼요.

기본적으로 이 transcript는 임시로만 존재합니다.

임시 디렉토리에 저장돼요.
blocking memory sub-agent 실행 중에만 사용돼요.
실행이 끝나면 즉시 삭제돼요.

디버깅이나 확인을 위해 이 transcript를 디스크에 남겨두고 싶다면, persistence 옵션을 직접 활성화해 주세요.

{
  plugins: {
    entries: {
      "active-memory": {
        enabled: true,
        config: {
          agents: ["main"],
          persistTranscripts: true,
          transcriptDir: "active-memory",
        },
      },
    },
  },
}

이 옵션을 활성화하면 active memory는 transcript를 메인 사용자 대화 경로가 아닌, 대상 agent의 sessions 폴더 아래 별도 디렉토리에 저장해요.

기본적인 구조는 다음과 같아요.

agents/<agent>/sessions/active-memory/<blocking-memory-sub-agent-session-id>.jsonl

config.transcriptDir를 통해 하위 디렉토리 이름을 바꿀 수 있어요.

사용할 때 주의할 점이 있어요.

사용량이 많은 세션에서는 transcript가 빠르게 쌓일 수 있어요.
full 쿼리 모드에서는 대화 맥락이 많이 중복될 수 있어요.
이 transcript에는 숨겨진 prompt context와 recall된 memory가 포함되어 있어요.

설정

모든 활성 메모리 설정은 다음 경로에서 관리해요:

plugins.entries.active-memory

가장 중요한 필드들은 다음과 같아요:

키	타입	의미
`enabled`	`boolean`	플러그인 자체를 활성화해요
`config.agents`	`string[]`	활성 메모리를 사용할 수 있는 Agent ID 목록이에요
`config.model`	`string`	선택 사항인 blocking memory sub-agent 모델 참조 값이에요. 설정하지 않으면 활성 메모리는 현재 세션 모델을 사용해요
`config.queryMode`	`"message" \| "recent" \| "full"`	blocking memory sub-agent가 대화 내용을 얼마나 참조할지 제어해요
`config.promptStyle`	`"balanced" \| "strict" \| "contextual" \| "recall-heavy" \| "precision-heavy" \| "preference-only"`	메모리를 반환할지 결정할 때 blocking memory sub-agent가 얼마나 적극적일지 또는 엄격할지 제어해요
`config.thinking`	`"off" \| "minimal" \| "low" \| "medium" \| "high" \| "xhigh" \| "adaptive"`	blocking memory sub-agent를 위한 고급 thinking 오버라이드 설정이에요. 속도를 위해 기본값은 `off`예요
`config.promptOverride`	`string`	고급 설정으로, 전체 프롬프트를 교체해요. 일반적인 사용 환경에서는 권장하지 않아요
`config.promptAppend`	`string`	기본 또는 교체된 프롬프트 뒤에 추가되는 고급 지침이에요
`config.timeoutMs`	`number`	blocking memory sub-agent에 적용되는 하드 타임아웃이에요
`config.maxSummaryChars`	`number`	active-memory 요약에 허용되는 최대 전체 글자 수예요
`config.logging`	`boolean`	튜닝하는 동안 활성 메모리 로그를 출력해요
`config.persistTranscripts`	`boolean`	임시 파일을 삭제하는 대신 blocking memory sub-agent 트랜스크립트를 디스크에 보관해요
`config.transcriptDir`	`string`	Agent 세션 폴더 아래에 생성될 blocking memory sub-agent 트랜스크립트 디렉터리 경로예요

튜닝에 유용한 필드들은 다음과 같아요:

키	타입	의미
`config.maxSummaryChars`	`number`	active-memory 요약에 허용되는 최대 전체 글자 수예요
`config.recentUserTurns`	`number`	`queryMode`가 `recent`일 때 포함할 이전 사용자 턴 수예요
`config.recentAssistantTurns`	`number`	`queryMode`가 `recent`일 때 포함할 이전 Assistant 턴 수예요
`config.recentUserChars`	`number`	최근 사용자 턴당 최대 글자 수예요
`config.recentAssistantChars`	`number`	최근 Assistant 턴당 최대 글자 수예요
`config.cacheTtlMs`	`number`	반복되는 동일한 쿼리에 대한 캐시 재사용 시간이에요

권장 설정

우선 recent 모드로 시작해 보세요.

{
  plugins: {
    entries: {
      "active-memory": {
        enabled: true,
        config: {
          agents: ["main"],
          queryMode: "recent",
          promptStyle: "balanced",
          timeoutMs: 15000,
          maxSummaryChars: 220,
          logging: true,
        },
      },
    },
  },
}

튜닝하면서 실시간 동작을 확인하고 싶다면, 별도의 active-memory 디버그 명령어를 찾는 대신 세션에서 /verbose on을 사용해 보세요.

그다음 필요에 따라 설정을 변경해 보세요:

낮은 지연 시간이 중요하다면 message를 선택하세요.
blocking memory sub-agent가 조금 느려지더라도 추가적인 컨텍스트를 확보하는 것이 중요하다면 full을 선택하세요.

디버깅

Active memory가 예상한 대로 나타나지 않는다면 다음 사항들을 확인해 보세요.

plugins.entries.active-memory.enabled 설정에서 플러그인이 활성화되어 있는지 확인합니다.
config.agents 목록에 현재 사용 중인 agent id가 포함되어 있는지 확인합니다.
대화형 persistent chat session을 통해 테스트하고 있는지 확인합니다.
config.logging: true 설정을 켜고 gateway 로그를 모니터링합니다.
openclaw memory status --deep 명령어를 사용해 memory search 자체가 잘 작동하는지 검증합니다.

만약 memory 검색 결과에 노이즈가 너무 많다면, 다음 설정을 조절해 보세요.

maxSummaryChars 값을 줄여서 범위를 좁힙니다.

Active memory 속도가 너무 느리다면 다음 방법들을 시도해 보세요.

queryMode 설정값을 낮춥니다.
timeoutMs 제한 시간을 줄입니다.
최근 대화 횟수(recent turn counts)를 줄입니다.
대화당 글자 수 제한(per-turn char caps)을 낮춥니다.

아직 막혀 있나요?

이 문서에서 답을 못 찾았다면 OpenClaw Expert에게 바로 물어보세요.

OpenClaw Active Memory 설정: 5분 만에 지능형 기억 기능 활성화

Active Memory

에이전트에 이 코드를 붙여넣으세요

Active Memory 활성화하기

작동 확인 방법

세션 토글

실행 시점

세션 유형

실행 위치

사용 이유

작동 원리

쿼리 모드 (Query modes)

프롬프트 스타일 (Prompt styles)

모델 폴백 정책 (Model fallback policy)

고급 탈출구 (Advanced escape hatches)

message

recent

full

Transcript persistence

설정

권장 설정

디버깅

관련 페이지

아직 막혀 있나요?

`message`

`recent`

`full`