English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย

Plugins

메모리 LanceDB

memory-lancedb는 장기 기억을 LanceDB에 저장하고 회상에 임베딩을 사용하는 번들 memory Plugin입니다. 모델 턴 전에 관련 기억을 자동으로 회상하고, 응답 후 중요한 사실을 캡처할 수 있습니다.

memory용 로컬 벡터 데이터베이스가 필요하거나, OpenAI 호환 임베딩 엔드포인트가 필요하거나, 기본 내장 memory 저장소 외부에 memory 데이터베이스를 유지하고 싶을 때 사용하세요.

빠른 시작

{
  plugins: {
    slots: {
      memory: "memory-lancedb",
    },
    entries: {
      "memory-lancedb": {
        enabled: true,
        config: {
          embedding: {
            provider: "openai",
            model: "text-embedding-3-small",
          },
          autoRecall: true,
          autoCapture: false,
        },
      },
    },
  },
}

Plugin 설정을 변경한 후 Gateway를 다시 시작하세요.

openclaw gateway restart

그런 다음 Plugin이 로드되었는지 확인하세요.

openclaw plugins list

제공자 기반 임베딩

memory-lancedb는 memory-core와 동일한 memory 임베딩 제공자 어댑터를 사용할 수 있습니다. 제공자의 구성된 인증 프로필, 환경 변수 또는 models.providers.<provider>.apiKey를 사용하려면 embedding.provider를 설정하고 embedding.apiKey는 생략하세요.

{
  plugins: {
    slots: {
      memory: "memory-lancedb",
    },
    entries: {
      "memory-lancedb": {
        enabled: true,
        config: {
          embedding: {
            provider: "openai",
            model: "text-embedding-3-small",
          },
          autoRecall: true,
        },
      },
    },
  },
}

이 경로는 임베딩 자격 증명을 노출하는 제공자 인증 프로필과 함께 작동합니다. 예를 들어 Copilot 프로필/플랜이 임베딩을 지원하면 GitHub Copilot을 사용할 수 있습니다.

{
  plugins: {
    slots: {
      memory: "memory-lancedb",
    },
    entries: {
      "memory-lancedb": {
        enabled: true,
        config: {
          embedding: {
            provider: "github-copilot",
            model: "text-embedding-3-small",
          },
        },
      },
    },
  },
}

OpenAI Codex / ChatGPT OAuth(openai-codex)는 OpenAI Platform 임베딩 자격 증명이 아닙니다. OpenAI 임베딩에는 OpenAI API 키 인증 프로필, OPENAI_API_KEY 또는 models.providers.openai.apiKey를 사용하세요. OAuth 전용 사용자는 GitHub Copilot이나 Ollama처럼 임베딩을 지원하는 다른 제공자를 사용할 수 있습니다.

Ollama 임베딩

Ollama 임베딩에는 번들 Ollama 임베딩 제공자를 사용하는 것을 권장합니다. 이 제공자는 네이티브 Ollama /api/embed 엔드포인트를 사용하며 Ollama에 문서화된 Ollama 제공자와 동일한 인증/base URL 규칙을 따릅니다.

{
  plugins: {
    slots: {
      memory: "memory-lancedb",
    },
    entries: {
      "memory-lancedb": {
        enabled: true,
        config: {
          embedding: {
            provider: "ollama",
            baseUrl: "http://127.0.0.1:11434",
            model: "mxbai-embed-large",
            dimensions: 1024,
          },
          recallMaxChars: 400,
          autoRecall: true,
          autoCapture: false,
        },
      },
    },
  },
}

비표준 임베딩 모델에는 dimensions를 설정하세요. OpenClaw는 text-embedding-3-small 및 text-embedding-3-large의 차원을 알고 있습니다. 사용자 지정 모델은 LanceDB가 벡터 열을 만들 수 있도록 설정에 값이 필요합니다.

작은 로컬 임베딩 모델의 경우, 로컬 서버에서 context 길이 오류가 보이면 recallMaxChars를 낮추세요.

OpenAI 호환 제공자

일부 OpenAI 호환 임베딩 제공자는 encoding_format 매개변수를 거부하지만, 다른 제공자는 이를 무시하고 항상 number[] 벡터를 반환합니다. 따라서 memory-lancedb는 임베딩 요청에서 encoding_format을 생략하고, float 배열 응답 또는 base64로 인코딩된 float32 응답을 모두 허용합니다.

번들 제공자 어댑터가 없는 원시 OpenAI 호환 임베딩 엔드포인트가 있다면 embedding.provider를 생략하거나 openai로 두고, embedding.apiKey와 embedding.baseUrl을 설정하세요. 이렇게 하면 직접 OpenAI 호환 클라이언트 경로가 유지됩니다.

모델 차원이 내장되어 있지 않은 제공자에는 embedding.dimensions를 설정하세요. 예를 들어 ZhiPu embedding-3는 2048 차원을 사용합니다.

{
  plugins: {
    entries: {
      "memory-lancedb": {
        enabled: true,
        config: {
          embedding: {
            apiKey: "${ZHIPU_API_KEY}",
            baseUrl: "https://open.bigmodel.cn/api/paas/v4",
            model: "embedding-3",
            dimensions: 2048,
          },
        },
      },
    },
  },
}

회상 및 캡처 제한

memory-lancedb에는 별도의 텍스트 제한이 두 가지 있습니다.

설정 기본값 범위 적용 대상
recallMaxChars 1000 100-10000 회상용 임베딩 API로 전송되는 텍스트
captureMaxChars 500 100-10000 캡처 대상으로 고려될 수 있는 assistant 메시지 길이

recallMaxChars는 자동 회상, memory_recall 도구, memory_forget 쿼리 경로, openclaw ltm search를 제어합니다. 자동 회상은 턴의 최신 사용자 메시지를 우선 사용하며, 사용자 메시지가 없을 때만 전체 프롬프트로 대체합니다. 이렇게 하면 채널 메타데이터와 큰 프롬프트 블록이 임베딩 요청에 포함되지 않습니다.

captureMaxChars는 응답이 자동 캡처 대상으로 고려될 만큼 짧은지 여부를 제어합니다. 회상 쿼리 임베딩에는 상한을 적용하지 않습니다.

명령

memory-lancedb가 Active Memory Plugin일 때는 ltm CLI 네임스페이스를 등록합니다.

openclaw ltm list
openclaw ltm search "project preferences"
openclaw ltm stats

이 Plugin은 LanceDB 테이블을 직접 대상으로 실행되는 비벡터 query 하위 명령으로 openclaw memory도 확장합니다.

openclaw memory query --cols id,text,createdAt --limit 20
openclaw memory query --filter "category = 'preference'" --order-by createdAt:desc
  • --cols <columns>: 쉼표로 구분된 열 허용 목록입니다. 기본값은 id, text, importance, category, createdAt입니다.
  • --filter <condition>: SQL 스타일 WHERE 절입니다. 200자로 제한되며 영숫자, 비교 연산자, 따옴표, 괄호, 그리고 안전한 일부 문장 부호로 제한됩니다.
  • --limit <n>: 양의 정수입니다. 기본값은 10입니다.
  • --order-by <column>:<asc|desc>: 필터 후 적용되는 메모리 내 정렬입니다. 정렬 열은 프로젝션에 자동으로 포함됩니다.

에이전트도 Active Memory Plugin에서 LanceDB memory 도구를 받습니다.

  • LanceDB 기반 회상을 위한 memory_recall
  • 중요한 사실, 선호도, 결정, 엔터티를 저장하기 위한 memory_store
  • 일치하는 기억을 제거하기 위한 memory_forget

저장소

기본적으로 LanceDB 데이터는 ~/.openclaw/memory/lancedb 아래에 있습니다. dbPath로 경로를 재정의하세요.

{
  plugins: {
    entries: {
      "memory-lancedb": {
        enabled: true,
        config: {
          dbPath: "~/.openclaw/memory/lancedb",
          embedding: {
            apiKey: "${OPENAI_API_KEY}",
            model: "text-embedding-3-small",
          },
        },
      },
    },
  },
}

storageOptions는 LanceDB 저장소 백엔드용 문자열 키/값 쌍을 받으며 ${ENV_VAR} 확장을 지원합니다.

{
  plugins: {
    entries: {
      "memory-lancedb": {
        enabled: true,
        config: {
          dbPath: "s3://memory-bucket/openclaw",
          storageOptions: {
            access_key: "${AWS_ACCESS_KEY_ID}",
            secret_key: "${AWS_SECRET_ACCESS_KEY}",
            endpoint: "${AWS_ENDPOINT_URL}",
          },
          embedding: {
            apiKey: "${OPENAI_API_KEY}",
            model: "text-embedding-3-small",
          },
        },
      },
    },
  },
}

Runtime 종속성

memory-lancedb는 네이티브 @lancedb/lancedb 패키지에 의존합니다. 패키징된 OpenClaw는 해당 패키지를 Plugin 패키지의 일부로 취급합니다. Gateway 시작은 Plugin 종속성을 복구하지 않습니다. 종속성이 누락된 경우 Plugin 패키지를 다시 설치하거나 업데이트한 뒤 Gateway를 다시 시작하세요.

이전 설치에서 Plugin 로드 중 누락된 dist/package.json 또는 누락된 @lancedb/lancedb 오류가 기록되면 OpenClaw를 업그레이드하고 Gateway를 다시 시작하세요.

Plugin이 LanceDB를 darwin-x64에서 사용할 수 없다고 기록하면, 해당 머신에서 기본 memory 백엔드를 사용하거나 Gateway를 지원되는 플랫폼으로 옮기거나 memory-lancedb를 비활성화하세요.

문제 해결

입력 길이가 context 길이를 초과함

이는 보통 임베딩 모델이 회상 쿼리를 거부했다는 의미입니다.

memory-lancedb: recall failed: Error: 400 the input length exceeds the context length

recallMaxChars를 더 낮게 설정한 다음 Gateway를 다시 시작하세요.

{
  plugins: {
    entries: {
      "memory-lancedb": {
        config: {
          recallMaxChars: 400,
        },
      },
    },
  },
}

Ollama의 경우, 임베딩 서버가 Gateway 호스트에서 접근 가능한지도 확인하세요.

curl http://127.0.0.1:11434/v1/embeddings \
  -H "Content-Type: application/json" \
  -d '{"model":"mxbai-embed-large","input":"hello"}'

지원되지 않는 임베딩 모델

dimensions가 없으면 내장 OpenAI 임베딩 차원만 알려져 있습니다. 로컬 또는 사용자 지정 임베딩 모델의 경우 embedding.dimensions를 해당 모델이 보고하는 벡터 크기로 설정하세요.

Plugin은 로드되지만 memory가 표시되지 않음

plugins.slots.memory가 memory-lancedb를 가리키는지 확인한 다음 실행하세요.

openclaw ltm stats
openclaw ltm search "recent preference"

autoCapture가 비활성화되어 있으면 Plugin은 기존 기억을 회상하지만 새 기억을 자동으로 저장하지 않습니다. 자동 캡처를 원한다면 memory_store 도구를 사용하거나 autoCapture를 활성화하세요.

관련 항목