Por que memory-lancedb-pro?

A maioria dos agentes de IA sofre de amnésia. Eles esquecem tudo no momento em que você inicia um novo chat.

memory-lancedb-pro é um plugin de memória de longo prazo de nível de produção para OpenClaw que transforma seu agente em um verdadeiro Assistente de Memória IA — captura automaticamente o que importa, deixa o ruído desaparecer naturalmente e recupera a memória certa no momento certo. Sem tags manuais, sem dores de cabeça com configuração.

Seu Assistente de Memória IA em ação

Sem memória — cada sessão começa do zero:

Você: "Use tabs para indentação, sempre adicione tratamento de erros." (próxima sessão) Você: "Eu já te disse — tabs, não espaços!" 😤 (próxima sessão) Você: "…sério, tabs. E tratamento de erros. De novo."

Com memory-lancedb-pro — seu agente aprende e lembra:

Você: "Use tabs para indentação, sempre adicione tratamento de erros." (próxima sessão — agente recupera automaticamente suas preferências) Agente: (aplica silenciosamente tabs + tratamento de erros) ✅ Você: "Por que escolhemos PostgreSQL em vez de MongoDB no mês passado?" Agente: "Com base na nossa discussão de 12 de fevereiro, os principais motivos foram…" ✅

Essa é a diferença que um Assistente de Memória IA faz — aprende seu estilo, lembra decisões passadas e entrega respostas personalizadas sem você precisar se repetir.

O que mais ele pode fazer?

Início rápido

Requisito de CPU: Sua CPU deve suportar instruções AVX/AVX2 (Intel Sandy Bridge 2011+ / AMD Bulldozer 2011+). O motor vetorial nativo do LanceDB requer essas instruções — em CPUs não compatíveis o plugin falhará com SIGILL (Instrução ilegal). Verifique com: grep -o 'avx[^ ]*' /proc/cpuinfo | head -1 (sem saída = não suportado). Veja #419.

Opção A: Script de instalação com um clique (recomendado)

O script de instalação mantido pela comunidade gerencia instalação, atualização e reparo em um único comando:

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

Veja Ecossistema abaixo para a lista completa de cenários cobertos e outras ferramentas da comunidade.

Opção B: Instalação manual

Via OpenClaw CLI (recomendado):

openclaw plugins install memory-lancedb-pro@beta

Ou via npm:

npm i memory-lancedb-pro@beta

Se usar npm, você também precisará adicionar o diretório de instalação do plugin como caminho absoluto em plugins.load.paths no seu openclaw.json. Este é o problema de configuração mais comum.

Adicione ao seu 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 }
        }
      }
    }
  }
}

Por que esses valores padrão?

• autoCapture + smartExtraction → seu agente aprende automaticamente de cada conversa
• autoRecall → memórias relevantes são injetadas antes de cada resposta
• extractMinMessages: 2 → a extração é acionada em chats normais de dois turnos
• sessionMemory.enabled: false → evita poluir a busca com resumos de sessão no início

Valide e reinicie:

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

Você deve ver:

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

Pronto! Seu agente agora tem memória de longo prazo.

# 1) Backup
openclaw memory-pro export --scope global --output memories-backup.json
# 2) Dry run
openclaw memory-pro upgrade --dry-run
# 3) Run upgrade
openclaw memory-pro upgrade
# 4) Verify
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

Ecossistema

memory-lancedb-pro é o plugin principal. A comunidade construiu ferramentas ao redor dele para tornar a configuração e o uso diário ainda mais suaves:

Script de instalação — Instalação, atualização e reparo com um clique

CortexReach/toolbox/memory-lancedb-pro-setup

Não é apenas um instalador simples — o script lida inteligentemente com diversos cenários reais:

bash setup-memory.sh                    # Install or upgrade
bash setup-memory.sh --dry-run          # Preview only
bash setup-memory.sh --beta             # Include pre-release versions
bash setup-memory.sh --uninstall        # Revert config and remove plugin

Presets de provedores integrados: Jina / DashScope / SiliconFlow / OpenAI / Ollama, ou traga sua própria API compatível com OpenAI. Para uso completo (incluindo --ref, --selfcheck-only e mais), veja o README do script de instalação.

Claude Code / OpenClaw Skill — Configuração guiada por IA

CortexReach/memory-lancedb-pro-skill

Instale esta Skill e seu agente de IA (Claude Code ou OpenClaw) ganha conhecimento profundo de todas as funcionalidades do memory-lancedb-pro. Basta dizer "me ajude a ativar a melhor configuração" e obtenha:

• Workflow de configuração guiado em 7 etapas com 4 planos de implantação:
  • Full Power (Jina + OpenAI) / Budget (reranker SiliconFlow gratuito) / Simple (apenas OpenAI) / Totalmente local (Ollama, custo API zero)
• Todas as 9 ferramentas MCP usadas corretamente: memory_recall, memory_store, memory_forget, memory_update, memory_stats, memory_list, self_improvement_log, self_improvement_extract_skill, self_improvement_review (o toolkit completo requer enableManagementTools: true — a configuração padrão do Quick Start expõe as 4 ferramentas principais)
• Prevenção de armadilhas comuns: ativação de plugin workspace, autoRecall padrão false, cache jiti, variáveis de ambiente, isolamento de scope, etc.

Instalação para Claude Code:

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

Instalação para OpenClaw:

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

Tutorial em vídeo

Guia completo: instalação, configuração e funcionamento interno da busca híbrida.

https://youtu.be/MtukF1C8epQ

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

Arquitetura

┌─────────────────────────────────────────────────────────┐
│                   index.ts (Entry Point)                │
│  Plugin Registration · Config Parsing · Lifecycle Hooks │
└────────┬──────────┬──────────┬──────────┬───────────────┘
         │          │          │          │
    ┌────▼───┐ ┌────▼───┐ ┌───▼────┐ ┌──▼──────────┐
    │ store  │ │embedder│ │retriever│ │   scopes    │
    │ .ts    │ │ .ts    │ │ .ts    │ │    .ts      │
    └────────┘ └────────┘ └────────┘ └─────────────┘
         │                     │
    ┌────▼───┐           ┌─────▼──────────┐
    │migrate │           │noise-filter.ts │
    │ .ts    │           │adaptive-       │
    └────────┘           │retrieval.ts    │
                         └────────────────┘
    ┌─────────────┐   ┌──────────┐
    │  tools.ts   │   │  cli.ts  │
    │ (Agent API) │   │ (CLI)    │
    └─────────────┘   └──────────┘

Para um mergulho profundo na arquitetura completa, veja docs/memory_architecture_analysis.md.

Funcionalidades principais

Busca híbrida

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

• Busca vetorial — similaridade semântica via LanceDB ANN (distância cosseno)
• Busca full-text BM25 — correspondência exata de palavras-chave via índice FTS do LanceDB
• Fusão híbrida — pontuação vetorial como base, resultados BM25 recebem boost ponderado (não é RRF padrão — ajustado para qualidade de recall no mundo real)
• Pesos configuráveis — vectorWeight, bm25Weight, minScore

Reranking Cross-Encoder

• Adaptadores integrados para Jina, SiliconFlow, Voyage AI e Pinecone
• Compatível com qualquer endpoint compatível com Jina (ex.: Hugging Face TEI, DashScope)
• Pontuação híbrida: 60% cross-encoder + 40% pontuação fundida original
• Degradação elegante: fallback para similaridade cosseno em caso de falha da API

Pipeline de pontuação multi-estágio

Extração inteligente de memória (v1.1.0)

• Extração LLM em 6 categorias: perfil, preferências, entidades, eventos, casos, padrões
• Armazenamento em camadas L0/L1/L2: L0 (índice em uma frase) → L1 (resumo estruturado) → L2 (narrativa completa)
• Deduplicação em dois estágios: pré-filtro de similaridade vetorial (≥0.7) → decisão semântica LLM (CREATE/MERGE/SKIP)
• Fusão consciente de categorias: profile sempre funde, events/cases apenas adicionam

Gerenciamento do ciclo de vida da memória (v1.1.0)

• Motor de decaimento Weibull: pontuação composta = frescor + frequência + valor intrínseco
• Promoção em três níveis: Peripheral ↔ Working ↔ Core com limiares configuráveis
• Reforço por acesso: memórias recuperadas frequentemente decaem mais lentamente (estilo repetição espaçada)
• Meia-vida modulada pela importância: memórias importantes decaem mais lentamente

Isolamento multi-scope

• Scopes integrados: global, agent:<id>, custom:<name>, project:<id>, user:<id>
• Controle de acesso no nível do agente via scopes.agentAccess
• Padrão: cada agente acessa global + seu próprio scope agent:<id>

Auto-Capture e Auto-Recall

• Auto-Capture (agent_end): extrai preferências/fatos/decisões/entidades das conversas, deduplica, armazena até 3 por turno
• Auto-Recall (before_agent_start): injeta contexto <relevant-memories> (até 3 entradas)

Filtragem de ruído e busca adaptativa

• Filtra conteúdo de baixa qualidade: recusas do agente, meta-perguntas, saudações
• Pula a busca para: saudações, comandos slash, confirmações simples, emoji
• Força a busca para palavras-chave de memória ("lembra", "anteriormente", "da última vez")
• Limiares CJK (chinês: 6 caracteres vs inglês: 15 caracteres)

Configuração

{
  "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
  }
}

Comandos 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]

Fluxo de login OAuth:

1. Execute openclaw memory-pro auth login
2. Se --provider for omitido em um terminal interativo, a CLI mostra um seletor de provedor OAuth antes de abrir o navegador
3. O comando imprime uma URL de autorização e abre seu navegador, a menos que --no-browser seja definido
4. Após o callback ser bem-sucedido, o comando salva o arquivo OAuth do plugin (padrão: ~/.openclaw/.memory-lancedb-pro/oauth.json), faz snapshot da configuração llm anterior (api-key) para logout, e substitui a configuração llm do plugin com as configurações OAuth (auth, oauthProvider, model, oauthPath)
5. openclaw memory-pro auth logout deleta esse arquivo OAuth e restaura a configuração llm anterior (api-key) quando esse snapshot existe

Tópicos avançados

{ "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.

Documentação

Beta: Smart Memory v1.1.0

Status: Beta — disponível via npm i memory-lancedb-pro@beta. Usuários estáveis no latest não são afetados.

Feedback: GitHub Issues · Reverter: npm i memory-lancedb-pro@latest

Dependências

Contributors

Full list: Contributors

Star History

Licença

MIT

Meu QR Code WeChat