왜 memory-lancedb-pro인가?

대부분의 AI 에이전트는 건망증이 있습니다. 새 채팅을 시작하는 순간 모든 것을 잊어버립니다.

memory-lancedb-pro는 OpenClaw를 위한 프로덕션 수준의 장기 기억 플러그인으로, 에이전트를 AI 메모리 어시스턴트로 바꿔줍니다 — 중요한 내용을 자동으로 캡처하고, 노이즈는 자연스럽게 희미해지게 하며, 적시에 적절한 기억을 검색합니다. 수동 태그 지정도, 복잡한 설정도 필요 없습니다.

AI 메모리 어시스턴트 실제 사용 모습

기억 없이 — 매 세션이 처음부터 시작:

사용자: "들여쓰기에 탭을 사용하고, 항상 에러 처리를 추가해." (다음 세션) 사용자: "이미 말했잖아 — 스페이스 말고 탭이라고!" 😤 (다음 세션) 사용자: "...진짜로, 탭이라고. 에러 처리도. 또."

memory-lancedb-pro와 함께 — 에이전트가 학습하고 기억합니다:

사용자: "들여쓰기에 탭을 사용하고, 항상 에러 처리를 추가해." (다음 세션 — 에이전트가 사용자 선호도를 자동으로 불러옴) 에이전트: (자동으로 탭 + 에러 처리 적용) ✅ 사용자: "지난달에 왜 MongoDB 대신 PostgreSQL을 선택했지?" 에이전트: "2월 12일 논의 내용에 따르면, 주요 이유는..." ✅

이것이 AI 메모리 어시스턴트가 만드는 차이입니다 — 사용자의 스타일을 학습하고, 과거 결정을 불러오며, 반복 없이 개인화된 응답을 제공합니다.

그 외 무엇을 할 수 있나요?

빠른 시작

CPU 요구사항: CPU가 AVX/AVX2 명령어 세트를 지원해야 합니다 (Intel Sandy Bridge 2011년 이후 / AMD Bulldozer 2011년 이후). LanceDB의 네이티브 벡터 엔진에 필수이며, 미지원 CPU에서는 플러그인이 SIGILL (잘못된 명령어)로 크래시됩니다. 확인 방법: grep -o 'avx[^ ]*' /proc/cpuinfo | head -1 (출력 없음 = 미지원). #419 참조.

옵션 A: 원클릭 설치 스크립트 (권장)

커뮤니티에서 관리하는 **설치 스크립트**가 설치, 업그레이드, 복구를 하나의 명령어로 처리합니다:

curl -fsSL https://raw.githubusercontent.com/CortexReach/toolbox/main/memory-lancedb-pro-setup/setup-memory.sh -o setup-memory.sh
bash setup-memory.sh

스크립트가 다루는 전체 시나리오와 기타 커뮤니티 도구 목록은 아래 에코시스템을 참조하세요.

옵션 B: 수동 설치

OpenClaw CLI를 통한 설치 (권장):

openclaw plugins install memory-lancedb-pro@beta

또는 npm을 통한 설치:

npm i memory-lancedb-pro@beta

npm을 사용하는 경우, openclaw.json의 plugins.load.paths에 플러그인 설치 디렉터리의 절대 경로를 추가해야 합니다. 이것이 가장 흔한 설정 문제입니다.

openclaw.json에 다음을 추가하세요:

{
  "plugins": {
    "slots": { "memory": "memory-lancedb-pro" },
    "entries": {
      "memory-lancedb-pro": {
        "enabled": true,
        "config": {
          "embedding": {
            "provider": "openai-compatible",
            "apiKey": "${OPENAI_API_KEY}",
            "model": "text-embedding-3-small"
          },
          "autoCapture": true,
          "autoRecall": true,
          "smartExtraction": true,
          "extractMinMessages": 2,
          "extractMaxChars": 8000,
          "sessionMemory": { "enabled": false }
        }
      }
    }
  }
}

왜 이러한 기본값인가?

• autoCapture + smartExtraction → 에이전트가 모든 대화에서 자동으로 학습
• autoRecall → 매 응답 전에 관련 기억이 주입됨
• extractMinMessages: 2 → 일반적인 두 턴 대화에서 추출이 시작됨
• sessionMemory.enabled: false → 초기에 세션 요약으로 검색이 오염되는 것을 방지

검증 및 재시작:

openclaw config validate
openclaw gateway restart
openclaw logs --follow --plain | grep "memory-lancedb-pro"

다음이 표시되어야 합니다:

• memory-lancedb-pro: smart extraction enabled
• memory-lancedb-pro@...: plugin registered

완료! 이제 에이전트가 장기 기억을 갖게 됩니다.

# 1) 백업
openclaw memory-pro export --scope global --output memories-backup.json
# 2) 시뮬레이션 실행
openclaw memory-pro upgrade --dry-run
# 3) 업그레이드 실행
openclaw memory-pro upgrade
# 4) 확인
openclaw memory-pro stats

Help me connect this memory plugin with the most user-friendly configuration: https://github.com/CortexReach/memory-lancedb-pro

Requirements:
1. Set it as the only active memory plugin
2. Use Jina for embedding, and set embedding.taskQuery=retrieval.query and embedding.taskPassage=retrieval.passage
3. Use Jina for reranker
4. Use gpt-4o-mini for the smart-extraction LLM
5. Enable autoCapture, autoRecall, smartExtraction
6. extractMinMessages=2
7. sessionMemory.enabled=false
8. captureAssistant=false
9. retrieval mode=hybrid, vectorWeight=0.7, bm25Weight=0.3
10. rerank=cross-encoder, candidatePoolSize=12, minScore=0.6, hardMinScore=0.62
11. Generate the final openclaw.json config directly, not just an explanation

에코시스템

memory-lancedb-pro는 핵심 플러그인입니다. 커뮤니티에서 설정과 일상적인 사용을 더욱 원활하게 만드는 도구들을 구축했습니다:

설치 스크립트 — 원클릭 설치, 업그레이드 및 복구

CortexReach/toolbox/memory-lancedb-pro-setup

단순한 인스톨러가 아닙니다 — 스크립트가 다양한 실제 시나리오를 지능적으로 처리합니다:

bash setup-memory.sh                    # 설치 또는 업그레이드
bash setup-memory.sh --dry-run          # 미리보기만
bash setup-memory.sh --beta             # 사전 릴리스 버전 포함
bash setup-memory.sh --uninstall        # 설정 복원 및 플러그인 제거

내장 프로바이더 프리셋: Jina / DashScope / SiliconFlow / OpenAI / Ollama, 또는 자체 OpenAI 호환 API를 사용할 수 있습니다. --ref, --selfcheck-only 등 전체 사용법은 설치 스크립트 README를 참조하세요.

Claude Code / OpenClaw Skill — AI 가이드 설정

CortexReach/memory-lancedb-pro-skill

이 Skill을 설치하면 AI 에이전트(Claude Code 또는 OpenClaw)가 memory-lancedb-pro의 모든 기능에 대한 깊은 지식을 갖게 됩니다. **"최적의 설정을 도와줘"**라고 말하면 다음을 제공합니다:

• 가이드 7단계 설정 워크플로우와 4가지 배포 계획:
  • Full Power (Jina + OpenAI) / Budget (무료 SiliconFlow 리랭커) / Simple (OpenAI만) / Fully Local (Ollama, API 비용 제로)
• 모든 9개 MCP 도구의 올바른 사용법: memory_recall, memory_store, memory_forget, memory_update, memory_stats, memory_list, self_improvement_log, self_improvement_extract_skill, self_improvement_review (전체 도구 세트를 사용하려면 enableManagementTools: true가 필요합니다 — 기본 빠른 시작 설정은 4개 핵심 도구만 노출합니다)
• 일반적인 함정 방지: 워크스페이스 플러그인 활성화, autoRecall 기본값 false, jiti 캐시, 환경 변수, 스코프 격리 등

Claude Code용 설치:

git clone https://github.com/CortexReach/memory-lancedb-pro-skill.git ~/.claude/skills/memory-lancedb-pro

OpenClaw용 설치:

git clone https://github.com/CortexReach/memory-lancedb-pro-skill.git ~/.openclaw/workspace/skills/memory-lancedb-pro-skill

비디오 튜토리얼

전체 안내: 설치, 설정, 하이브리드 검색 내부 구조.

https://youtu.be/MtukF1C8epQ

https://www.bilibili.com/video/BV1zUf2BGEgn/

아키텍처

┌─────────────────────────────────────────────────────────┐
│                   index.ts (진입점)                      │
│  플러그인 등록 · 설정 파싱 · 라이프사이클 훅              │
└────────┬──────────┬──────────┬──────────┬───────────────┘
         │          │          │          │
    ┌────▼───┐ ┌────▼───┐ ┌───▼────┐ ┌──▼──────────┐
    │ store  │ │embedder│ │retriever│ │   scopes    │
    │ .ts    │ │ .ts    │ │ .ts    │ │    .ts      │
    └────────┘ └────────┘ └────────┘ └─────────────┘
         │                     │
    ┌────▼───┐           ┌─────▼──────────┐
    │migrate │           │noise-filter.ts │
    │ .ts    │           │adaptive-       │
    └────────┘           │retrieval.ts    │
                         └────────────────┘
    ┌─────────────┐   ┌──────────┐
    │  tools.ts   │   │  cli.ts  │
    │ (에이전트API)│   │ (CLI)    │
    └─────────────┘   └──────────┘

전체 아키텍처에 대한 심층 분석은 docs/memory_architecture_analysis.md를 참조하세요.

핵심 기능

하이브리드 검색

Query → embedQuery() ─┐
                       ├─→ Hybrid Fusion → Rerank → Lifecycle Decay Boost → Length Norm → Filter
Query → BM25 FTS ─────┘

• 벡터 검색 — LanceDB ANN을 통한 의미적 유사도 (코사인 거리)
• BM25 전문 검색 — LanceDB FTS 인덱스를 통한 정확한 키워드 매칭
• 하이브리드 퓨전 — 벡터 스코어를 기본으로, BM25 히트에 가중 부스트 적용 (표준 RRF가 아님 — 실제 검색 품질에 맞게 튜닝됨)
• 가중치 설정 가능 — vectorWeight, bm25Weight, minScore

Cross-Encoder 리랭킹

• Jina, SiliconFlow, Voyage AI, Pinecone 내장 어댑터
• Jina 호환 엔드포인트와 호환 (예: Hugging Face TEI, DashScope)
• 하이브리드 스코어링: Cross-Encoder 60% + 원래 퓨전 스코어 40%
• 그레이스풀 디그레이데이션: API 실패 시 코사인 유사도로 폴백

다단계 스코어링 파이프라인

Smart Memory Extraction (v1.1.0)

• LLM 기반 6개 카테고리 추출: profile, preferences, entities, events, cases, patterns
• L0/L1/L2 계층 저장: L0 (한 줄 인덱스) → L1 (구조화된 요약) → L2 (전체 내러티브)
• 2단계 중복 제거: 벡터 유사도 사전 필터 (≥0.7) → LLM 의미 판단 (CREATE/MERGE/SKIP)
• 카테고리 인식 병합: profile은 항상 병합, events/cases는 추가 전용

메모리 라이프사이클 관리 (v1.1.0)

• Weibull 감쇠 엔진: 복합 점수 = 최신성 + 빈도 + 내재적 가치
• 3단계 승격: Peripheral ↔ Working ↔ Core, 설정 가능한 임계값
• 접근 강화: 자주 불러오는 기억은 더 느리게 감쇠 (간격 반복 학습 방식)
• 중요도 조절 반감기: 중요한 기억은 더 느리게 감쇠

Multi-Scope 격리

• 내장 스코프: global, agent:<id>, custom:<name>, project:<id>, user:<id>
• scopes.agentAccess를 통한 에이전트 수준 접근 제어
• 기본값: 각 에이전트가 global + 자체 agent:<id> 스코프에 접근

Auto-Capture 및 Auto-Recall

• Auto-Capture (agent_end): 대화에서 선호도/사실/결정/엔티티를 추출, 중복 제거, 턴당 최대 3개 저장
• Auto-Recall (before_agent_start): <relevant-memories> 컨텍스트 주입 (최대 3개 항목)

노이즈 필터링 및 적응형 검색

• 저품질 콘텐츠 필터링: 에이전트 거절, 메타 질문, 인사
• 인사, 슬래시 명령어, 간단한 확인, 이모지에 대해서는 검색 건너뜀
• 기억 키워드에 대해서는 검색 강제 실행 ("기억해", "이전에", "지난번에")
• CJK 인식 임계값 (중국어: 6자 vs 영어: 15자)

설정

{
  "embedding": {
    "apiKey": "${JINA_API_KEY}",
    "model": "jina-embeddings-v5-text-small",
    "baseURL": "https://api.jina.ai/v1",
    "dimensions": 1024,
    "taskQuery": "retrieval.query",
    "taskPassage": "retrieval.passage",
    "normalized": true
  },
  "dbPath": "~/.openclaw/memory/lancedb-pro",
  "autoCapture": true,
  "autoRecall": true,
  "retrieval": {
    "mode": "hybrid",
    "vectorWeight": 0.7,
    "bm25Weight": 0.3,
    "minScore": 0.3,
    "rerank": "cross-encoder",
    "rerankApiKey": "${JINA_API_KEY}",
    "rerankModel": "jina-reranker-v3",
    "rerankEndpoint": "https://api.jina.ai/v1/rerank",
    "rerankProvider": "jina",
    "candidatePoolSize": 20,
    "recencyHalfLifeDays": 14,
    "recencyWeight": 0.1,
    "filterNoise": true,
    "lengthNormAnchor": 500,
    "hardMinScore": 0.35,
    "timeDecayHalfLifeDays": 60,
    "reinforcementFactor": 0.5,
    "maxHalfLifeMultiplier": 3
  },
  "enableManagementTools": false,
  "scopes": {
    "default": "global",
    "definitions": {
      "global": { "description": "Shared knowledge" },
      "agent:discord-bot": { "description": "Discord bot private" }
    },
    "agentAccess": {
      "discord-bot": ["global", "agent:discord-bot"]
    }
  },
  "sessionMemory": {
    "enabled": false,
    "messageCount": 15
  },
  "smartExtraction": true,
  "llm": {
    "apiKey": "${OPENAI_API_KEY}",
    "model": "gpt-4o-mini",
    "baseURL": "https://api.openai.com/v1"
  },
  "extractMinMessages": 2,
  "extractMaxChars": 8000
}

{
  "llm": {
    "auth": "oauth",
    "oauthProvider": "openai-codex",
    "model": "gpt-5.4",
    "oauthPath": "${HOME}/.openclaw/.memory-lancedb-pro/oauth.json",
    "timeoutMs": 30000
  }
}

CLI 명령어

openclaw memory-pro list [--scope global] [--category fact] [--limit 20] [--json]
openclaw memory-pro search "query" [--scope global] [--limit 10] [--json]
openclaw memory-pro stats [--scope global] [--json]
openclaw memory-pro auth login [--provider openai-codex] [--model gpt-5.4] [--oauth-path /abs/path/oauth.json]
openclaw memory-pro auth status
openclaw memory-pro auth logout
openclaw memory-pro delete <id>
openclaw memory-pro delete-bulk --scope global [--before 2025-01-01] [--dry-run]
openclaw memory-pro export [--scope global] [--output memories.json]
openclaw memory-pro import memories.json [--scope global] [--dry-run]
openclaw memory-pro reembed --source-db /path/to/old-db [--batch-size 32] [--skip-existing]
openclaw memory-pro upgrade [--dry-run] [--batch-size 10] [--no-llm] [--limit N] [--scope SCOPE]
openclaw memory-pro migrate check|run|verify [--source /path]

OAuth 로그인 흐름:

1. openclaw memory-pro auth login 실행
2. --provider를 생략하고 대화형 터미널에서 실행하면, 브라우저를 열기 전에 CLI가 OAuth 프로바이더 선택기를 표시합니다
3. 명령어가 인증 URL을 출력하고 --no-browser가 설정되지 않은 한 브라우저를 엽니다
4. 콜백이 성공하면, 명령어가 플러그인 OAuth 파일 (기본값: ~/.openclaw/.memory-lancedb-pro/oauth.json)을 저장하고, 이전 api-key llm 설정의 스냅샷을 로그아웃용으로 저장하며, 플러그인 llm 설정을 OAuth 설정 (auth, oauthProvider, model, oauthPath)으로 교체합니다
5. openclaw memory-pro auth logout은 해당 OAuth 파일을 삭제하고 스냅샷이 존재하면 이전 api-key llm 설정을 복원합니다

고급 주제

{ "plugins": { "entries": { "memory-lancedb-pro": { "config": { "autoRecall": false } } } } }

## /lesson command
When the user sends `/lesson <content>`:
1. Use memory_store to save as category=fact (raw knowledge)
2. Use memory_store to save as category=decision (actionable takeaway)
3. Confirm what was saved

## /remember command
When the user sends `/remember <content>`:
1. Use memory_store to save with appropriate category and importance
2. Confirm with the stored memory ID

## Rule 1 — Dual-layer memory storage
Every pitfall/lesson learned → IMMEDIATELY store TWO memories:
- Technical layer: Pitfall: [symptom]. Cause: [root cause]. Fix: [solution]. Prevention: [how to avoid]
  (category: fact, importance >= 0.8)
- Principle layer: Decision principle ([tag]): [behavioral rule]. Trigger: [when]. Action: [what to do]
  (category: decision, importance >= 0.85)

## Rule 2 — LanceDB hygiene
Entries must be short and atomic (< 500 chars). No raw conversation summaries or duplicates.

## Rule 3 — Recall before retry
On ANY tool failure, ALWAYS memory_recall with relevant keywords BEFORE retrying.

## Rule 4 — Confirm target codebase
Confirm you are editing memory-lancedb-pro vs built-in memory-lancedb before changes.

## Rule 5 — Clear jiti cache after plugin code changes
After modifying .ts files under plugins/, MUST run rm -rf /tmp/jiti/ BEFORE openclaw gateway restart.

문서

베타: Smart Memory v1.1.0

상태: 베타 — npm i memory-lancedb-pro@beta로 사용 가능. latest를 사용하는 안정 버전 사용자는 영향 없음.

피드백: GitHub Issues · 되돌리기: npm i memory-lancedb-pro@latest

의존성

Contributors

Full list: Contributors

Star History

라이선스

MIT

WeChat QR 코드