حافظه LanceDB

memory-lancedb یک Plugin حافظه‌ی bundled است که حافظه‌ی بلندمدت را در LanceDB ذخیره می‌کند و از embeddingها برای recall استفاده می‌کند. می‌تواند پیش از نوبت مدل، حافظه‌های مرتبط را به‌طور خودکار recall کند و پس از یک پاسخ، facts مهم را capture کند.

وقتی از آن استفاده کنید که یک پایگاه‌داده‌ی برداری محلی برای حافظه می‌خواهید، به یک endpoint embedding سازگار با OpenAI نیاز دارید، یا می‌خواهید پایگاه‌داده‌ی حافظه را بیرون از memory store داخلی پیش‌فرض نگه دارید.

# شروع سریع

{
  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

# embeddingهای پشتیبانی‌شده توسط provider

memory-lancedb می‌تواند از همان adapterهای provider embedding حافظه استفاده کند که memory-core استفاده می‌کند. embedding.provider را تنظیم کنید و embedding.apiKey را حذف کنید تا از auth profile پیکربندی‌شده‌ی provider، متغیر محیطی، یا models.providers.<provider>.apiKey استفاده شود.

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

این مسیر با auth profileهای provider که credentialهای embedding را ارائه می‌کنند کار می‌کند. برای مثال، وقتی profile/plan مربوط به Copilot از embeddingها پشتیبانی کند، می‌توان از 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) یک credential embedding مربوط به OpenAI Platform نیست. برای embeddingهای OpenAI، از یک auth profile با کلید OpenAI API، OPENAI_API_KEY، یا models.providers.openai.apiKey استفاده کنید. کاربران فقط-OAuth می‌توانند از provider دیگری با قابلیت embedding مانند GitHub Copilot یا Ollama استفاده کنند.

# embeddingهای Ollama

برای embeddingهای Ollama، provider embedding داخلی Ollama را ترجیح دهید. این provider از endpoint بومی Ollama یعنی /api/embed استفاده می‌کند و همان قواعد auth/base URL را دنبال می‌کند که برای provider Ollama در Ollama مستند شده‌اند.

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

برای مدل‌های embedding غیراستاندارد، dimensions را تنظیم کنید. OpenClaw ابعاد text-embedding-3-small و text-embedding-3-large را می‌داند؛ مدل‌های سفارشی به مقدار در پیکربندی نیاز دارند تا LanceDB بتواند ستون برداری را ایجاد کند.

برای مدل‌های embedding محلی کوچک، اگر از server محلی خطاهای طول context می‌بینید، recallMaxChars را کاهش دهید.

# providerهای سازگار با OpenAI

برخی providerهای embedding سازگار با OpenAI پارامتر encoding_format را رد می‌کنند، در حالی که برخی دیگر آن را نادیده می‌گیرند و همیشه بردارهای number[] برمی‌گردانند. بنابراین memory-lancedb در درخواست‌های embedding، encoding_format را حذف می‌کند و هم پاسخ‌های float-array و هم پاسخ‌های float32 کدگذاری‌شده با base64 را می‌پذیرد.

اگر یک endpoint خام embedding سازگار با OpenAI دارید که adapter provider داخلی ندارد، embedding.provider را حذف کنید (یا آن را به‌صورت openai باقی بگذارید) و embedding.apiKey را همراه با embedding.baseUrl تنظیم کنید. این کار مسیر مستقیم client سازگار با OpenAI را حفظ می‌کند.

برای providerهایی که ابعاد مدلشان به‌صورت داخلی شناخته‌شده نیست، 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,
          },
        },
      },
    },
  },
}

# محدودیت‌های recall و capture

memory-lancedb دو محدودیت جداگانه برای متن دارد:

تنظیمات	پیش‌فرض	بازه	اعمال می‌شود به
recallMaxChars	1000	100-10000	متنی که برای recall به API embedding ارسال می‌شود
captureMaxChars	500	100-10000	طول پیام assistant که برای capture واجد شرایط است

recallMaxChars، auto-recall، ابزار memory_recall، مسیر query مربوط به memory_forget، و openclaw ltm search را کنترل می‌کند. Auto-recall آخرین پیام user از آن turn را ترجیح می‌دهد و فقط وقتی هیچ پیام user در دسترس نباشد به prompt کامل fallback می‌کند. این کار metadataهای channel و blockهای بزرگ prompt را از درخواست embedding بیرون نگه می‌دارد.

captureMaxChars کنترل می‌کند که آیا یک پاسخ به‌اندازه‌ی کافی کوتاه هست تا برای capture خودکار در نظر گرفته شود یا نه. این مقدار embeddingهای query مربوط به recall را محدود نمی‌کند.

# دستورها

وقتی memory-lancedb Plugin حافظه‌ی فعال باشد، namespace مربوط به ltm در CLI را ثبت می‌کند:

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

این Plugin همچنین openclaw memory را با یک subcommand غیر برداری به نام query گسترش می‌دهد که مستقیماً روی جدول LanceDB اجرا می‌شود:

openclaw memory query --cols id,text,createdAt --limit 20
openclaw memory query --filter "category = 'preference'" --order-by createdAt:desc

• --cols <columns>: allowlist ستون‌های جداشده با کاما (به‌طور پیش‌فرض id، text، importance، category، createdAt).
• --filter <condition>: بند WHERE به سبک SQL؛ به ۲۰۰ نویسه محدود شده و به حروف و اعداد، عملگرهای مقایسه، quoteها، پرانتزها، و مجموعه‌ی کوچکی از نشانه‌گذاری امن محدود است.
• --limit <n>: عدد صحیح مثبت؛ پیش‌فرض 10.
• --order-by <column>:<asc|desc>: مرتب‌سازی درون حافظه که پس از filter اعمال می‌شود؛ ستون مرتب‌سازی به‌طور خودکار در projection وارد می‌شود.

Agentها همچنین ابزارهای حافظه‌ی LanceDB را از Plugin حافظه‌ی فعال دریافت می‌کنند:

• memory_recall برای recall پشتیبانی‌شده توسط LanceDB
• memory_store برای ذخیره‌ی facts، preferences، decisions و entities مهم
• memory_forget برای حذف حافظه‌های مطابق

# ذخیره‌سازی

به‌طور پیش‌فرض، داده‌های LanceDB زیر ~/.openclaw/memory/lancedb قرار می‌گیرند. مسیر را با dbPath override کنید:

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

storageOptions جفت‌های کلید/مقدار رشته‌ای را برای backendهای ذخیره‌سازی 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 به package بومی @lancedb/lancedb وابسته است. OpenClaw بسته‌بندی‌شده آن package را بخشی از package مربوط به Plugin در نظر می‌گیرد. startup مربوط به Gateway وابستگی‌های Plugin را repair نمی‌کند؛ اگر dependency وجود ندارد، package مربوط به Plugin را دوباره نصب یا update کنید و Gateway را restart کنید.

اگر یک نصب قدیمی هنگام load شدن Plugin خطای missing dist/package.json یا missing @lancedb/lancedb را log کرد، OpenClaw را upgrade کنید و Gateway را restart کنید.

اگر Plugin log کرد که LanceDB روی darwin-x64 در دسترس نیست، از backend حافظه‌ی پیش‌فرض روی آن machine استفاده کنید، Gateway را به platform پشتیبانی‌شده منتقل کنید، یا memory-lancedb را disable کنید.

# عیب‌یابی

# طول input از طول context فراتر می‌رود

این معمولاً یعنی مدل embedding، query مربوط به recall را رد کرده است:

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

recallMaxChars را روی مقدار کمتری تنظیم کنید، سپس Gateway را restart کنید:

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

برای Ollama، همچنین بررسی کنید که server embedding از host مربوط به Gateway قابل دسترسی باشد:

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

# مدل embedding پشتیبانی‌نشده

بدون dimensions، فقط ابعاد embedding داخلی OpenAI شناخته شده‌اند. برای مدل‌های embedding محلی یا سفارشی، embedding.dimensions را روی اندازه‌ی برداری تنظیم کنید که آن مدل گزارش می‌کند.

# Plugin load می‌شود اما هیچ حافظه‌ای ظاهر نمی‌شود

بررسی کنید که plugins.slots.memory به memory-lancedb اشاره کند، سپس اجرا کنید:

openclaw ltm stats
openclaw ltm search "recent preference"

اگر autoCapture غیرفعال باشد، Plugin حافظه‌های موجود را recall می‌کند اما موارد جدید را به‌طور خودکار ذخیره نمی‌کند. اگر capture خودکار می‌خواهید، از ابزار memory_store استفاده کنید یا autoCapture را فعال کنید.

# مرتبط

• نمای کلی حافظه
• Active memory
• جستجوی حافظه
• Memory Wiki
• Ollama