내장 메모리 엔진

내장 엔진은 기본 메모리 백엔드입니다. 에이전트별 SQLite 데이터베이스에 메모리 인덱스를 저장하며, 시작하는 데 추가 종속성이 필요하지 않습니다.

제공 기능

• FTS5 전문 인덱싱(BM25 점수 산정)을 통한 키워드 검색.
• 지원되는 모든 제공자의 임베딩을 통한 벡터 검색.
• 최상의 결과를 위해 두 방식을 결합하는 하이브리드 검색.
• 중국어, 일본어, 한국어를 위한 트라이그램 토큰화를 통한 CJK 지원.
• 데이터베이스 내 벡터 쿼리를 위한 sqlite-vec 가속(선택 사항).

시작하기

기본적으로 내장 엔진은 OpenAI 임베딩을 사용합니다. OPENAI_API_KEY 또는 models.providers.openai.apiKey가 이미 구성되어 있으면 추가 메모리 구성 없이 벡터 검색이 작동합니다.

제공자를 명시적으로 설정하려면 다음과 같이 구성합니다.

{  agents: {    defaults: {      memorySearch: {        provider: "openai",      },    },  },}

임베딩 제공자가 없으면 키워드 검색만 사용할 수 있습니다.

로컬 GGUF 임베딩을 강제로 사용하려면 공식 llama.cpp 제공자 Plugin을 설치한 다음 local.modelPath가 GGUF 파일을 가리키도록 설정합니다.

openclaw plugins install @openclaw/llama-cpp-provider

{  agents: {    defaults: {      memorySearch: {        provider: "local",        fallback: "none",        local: {          modelPath: "~/.node-llama-cpp/models/embeddinggemma-300m-qat-Q8_0.gguf",        },      },    },  },}

지원되는 임베딩 제공자

OpenAI 이외의 제공자로 전환하려면 memorySearch.provider를 설정합니다.

인덱싱 작동 방식

OpenClaw는 MEMORY.md와 memory/*.md를 청크(기본값: 400토큰, 80토큰 중첩)로 인덱싱하여 에이전트별 SQLite 데이터베이스에 저장합니다.

• 인덱스 위치: 소유 에이전트의 데이터베이스인 ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite
• 저장소 유지 관리: SQLite WAL 사이드카는 주기적인 체크포인트와 종료 시 체크포인트를 통해 크기가 제한됩니다.
• 파일 감시: 메모리 파일이 변경되면 디바운스된 재인덱싱이 실행됩니다(기본값 1.5초).
• 자동 재인덱싱: 임베딩 제공자, 모델, 청킹 구성, 구성된 소스 또는 범위가 변경되면 인덱스가 자동으로 다시 빌드됩니다.
• 요청 시 재인덱싱: openclaw memory index --force

사용 시점

내장 엔진은 대부분의 사용자에게 적합합니다.

• 추가 종속성 없이 즉시 작동합니다.
• 키워드 검색과 벡터 검색을 모두 효과적으로 처리합니다.
• 모든 임베딩 제공자를 지원합니다.
• 하이브리드 검색은 두 검색 방식의 장점을 결합합니다.

재순위 지정, 쿼리 확장이 필요하거나 작업 공간 외부의 디렉터리를 인덱싱하려면 QMD로 전환하는 것을 고려하세요.

자동 사용자 모델링을 지원하는 세션 간 메모리를 원한다면 Honcho를 고려하세요.

문제 해결

메모리 검색이 비활성화되었나요? openclaw memory status를 확인하세요. 제공자가 감지되지 않으면 제공자를 명시적으로 설정하거나 API 키를 추가하세요.

로컬 제공자가 감지되지 않나요? 로컬 경로가 존재하는지 확인하고 다음 명령을 실행하세요.

openclaw memory status --deep --agent mainopenclaw memory index --force --agent main

독립 실행형 CLI 명령과 Gateway는 모두 동일한 local 제공자 ID를 사용합니다. 로컬 임베딩을 사용하려면 memorySearch.provider: "local"을 설정하세요.

결과가 오래되었나요? 다시 빌드하려면 openclaw memory index --force를 실행하세요. 드문 경계 사례에서는 감시기가 변경 사항을 놓칠 수 있습니다.

sqlite-vec가 로드되지 않나요? OpenClaw는 자동으로 프로세스 내 코사인 유사도 방식으로 대체합니다. openclaw memory status --deep는 로컬 벡터 저장소를 임베딩 제공자와 별도로 보고하므로, Vector store: unavailable은 sqlite-vec 로드 문제를 나타내고 Embeddings: unavailable은 제공자/인증 또는 모델 준비 상태 문제를 나타냅니다. 구체적인 로드 오류는 로그에서 확인하세요.

구성

임베딩 제공자 설정, 하이브리드 검색 조정(가중치, MMR, 시간 감쇠), 일괄 인덱싱, 멀티모달 메모리, sqlite-vec, 추가 경로 및 기타 모든 구성 옵션은 메모리 구성 참조를 확인하세요.

관련 문서

• 메모리 개요
• 메모리 검색
• Active Memory