مرجع پیکربندی حافظه

این صفحه همهٔ تنظیمات قابل پیکربندی برای جستجوی حافظهٔ OpenClaw را فهرست می‌کند. برای مرورهای مفهومی، ببینید:

همهٔ تنظیمات جستجوی حافظه، مگر اینکه خلافش ذکر شده باشد، زیر agents.defaults.memorySearch در openclaw.json قرار دارند.

# انتخاب provider

# ترتیب شناسایی خودکار

وقتی provider تنظیم نشده باشد، OpenClaw اولین گزینهٔ در دسترس را انتخاب می‌کند:

ollama پشتیبانی می‌شود اما به‌صورت خودکار شناسایی نمی‌شود (آن را صریحاً تنظیم کنید).

# شناسه‌های provider سفارشی

memorySearch.provider می‌تواند به یک ورودی سفارشی models.providers.<id> اشاره کند. OpenClaw مالک api آن provider را برای adapter مربوط به embedding resolve می‌کند، درحالی‌که شناسهٔ provider سفارشی را برای endpoint، احراز هویت، و مدیریت پیشوند مدل حفظ می‌کند. این به راه‌اندازی‌های چند-GPU یا چند-host اجازه می‌دهد embeddingهای حافظه را به یک endpoint محلی مشخص اختصاص دهند:

{
  models: {
    providers: {
      "ollama-5080": {
        api: "ollama",
        baseUrl: "http://gpu-box.local:11435",
        apiKey: "ollama-local",
        models: [{ id: "qwen3-embedding:0.6b" }],
      },
    },
  },
  agents: {
    defaults: {
      memorySearch: {
        provider: "ollama-5080",
        model: "qwen3-embedding:0.6b",
      },
    },
  },
}

# resolve کردن کلید API

embeddingهای راه دور به کلید API نیاز دارند. Bedrock به‌جای آن از زنجیرهٔ اعتبارنامهٔ پیش‌فرض AWS SDK استفاده می‌کند (نقش‌های instance، SSO، کلیدهای دسترسی).

# پیکربندی endpoint راه دور

برای endpointهای سفارشی سازگار با OpenAI یا بازنویسی پیش‌فرض‌های provider:

{
  agents: {
    defaults: {
      memorySearch: {
        provider: "openai",
        model: "text-embedding-3-small",
        remote: {
          baseUrl: "https://api.example.com/v1/",
          apiKey: "YOUR_KEY",
        },
      },
    },
  },
}

# پیکربندی ویژهٔ provider

{
  agents: {
    defaults: {
      memorySearch: {
        provider: "openai",
        remote: {
          baseUrl: "https://embeddings.example/v1",
          apiKey: "env:EMBEDDINGS_API_KEY",
        },
        model: "asymmetric-embedder",
        queryInputType: "query",
        documentInputType: "passage",
      },
    },
  },
}

{
  agents: {
    defaults: {
      memorySearch: {
        provider: "bedrock",
        model: "amazon.titan-embed-text-v2:0",
      },
    },
  },
}

{
  "Effect": "Allow",
  "Action": "bedrock:InvokeModel",
  "Resource": "*"
}

arn:aws:bedrock:*::foundation-model/amazon.titan-embed-text-v2:0

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

# مهلت زمانی embedding درون‌خطی

# پیکربندی جست‌وجوی ترکیبی

همه زیر memorySearch.query.hybrid:

# نمونه کامل

{
  agents: {
    defaults: {
      memorySearch: {
        query: {
          hybrid: {
            vectorWeight: 0.7,
            textWeight: 0.3,
            mmr: { enabled: true, lambda: 0.7 },
            temporalDecay: { enabled: true, halfLifeDays: 30 },
          },
        },
      },
    },
  },
}

# مسیرهای حافظه اضافی

{
  agents: {
    defaults: {
      memorySearch: {
        extraPaths: ["../team-docs", "/srv/shared-notes"],
      },
    },
  },
}

مسیرها می‌توانند مطلق یا نسبی به workspace باشند. پوشه‌ها به‌صورت بازگشتی برای فایل‌های .md پویش می‌شوند. نحوه مدیریت symlink به backend فعال بستگی دارد: موتور داخلی symlinkها را نادیده می‌گیرد، در حالی که QMD از رفتار scanner زیربنایی QMD پیروی می‌کند.

برای جست‌وجوی transcript میان-agent با محدوده agent، به‌جای memory.qmd.paths از agents.list[].memorySearch.qmd.extraCollections استفاده کنید. آن collectionهای اضافی همان شکل { path, name, pattern? } را دنبال می‌کنند، اما به‌ازای هر agent ادغام می‌شوند و وقتی مسیر به خارج از workspace فعلی اشاره می‌کند، می‌توانند نام‌های مشترک صریح را حفظ کنند. اگر همان مسیر resolve‌شده هم در memory.qmd.paths و هم در memorySearch.qmd.extraCollections ظاهر شود، QMD ورودی اول را نگه می‌دارد و مورد تکراری را رد می‌کند.

# حافظه چندوجهی (Gemini)

تصاویر و صدا را در کنار Markdown با استفاده از Gemini Embedding 2 نمایه‌سازی کنید:

قالب‌های پشتیبانی‌شده: .jpg، .jpeg، .png، .webp، .gif، .heic، .heif (تصاویر)؛ .mp3، .wav، .ogg، .opus، .m4a، .aac، .flac (صوت).

# حافظهٔ نهان تعبیه

از تعبیهٔ دوبارهٔ متنِ بدون تغییر هنگام نمایه‌سازی دوباره یا به‌روزرسانی transcript جلوگیری می‌کند.

# نمایه‌سازی دسته‌ای

برای openai، gemini و voyage در دسترس است. دسته‌ای OpenAI معمولا برای backfillهای بزرگ سریع‌ترین و کم‌هزینه‌ترین گزینه است.

remote.nonBatchConcurrency فراخوانی‌های تعبیهٔ درون‌خطی را کنترل می‌کند که providerهای محلی/self-hosted و providerهای میزبانی‌شده زمانی استفاده می‌کنند که APIهای دسته‌ای provider فعال نیستند. مقدار پیش‌فرض Ollama برای نمایه‌سازی غیردسته‌ای 1 است تا از overload شدن میزبان‌های محلی کوچک‌تر جلوگیری شود؛ روی ماشین‌های بزرگ‌تر مقدار بالاتری تنظیم کنید.

این جدا از sync.embeddingBatchTimeoutSeconds است که timeout فراخوانی‌های تعبیهٔ درون‌خطی را کنترل می‌کند.

# جست‌وجوی حافظهٔ نشست (آزمایشی)

transcriptهای نشست را نمایه‌سازی کنید و آن‌ها را از طریق memory_search ارائه دهید:

# شتاب‌دهی برداری SQLite (sqlite-vec)

وقتی sqlite-vec در دسترس نباشد، OpenClaw به‌طور خودکار به شباهت کسینوسی درون‌فرآیندی fallback می‌کند.

# ذخیره‌سازی نمایه

# پیکربندی backend مربوط به QMD

برای فعال‌سازی، memory.backend = "qmd" را تنظیم کنید. همهٔ تنظیمات QMD زیر memory.qmd قرار دارند:

searchMode: "search" فقط واژگانی/BM25 است. OpenClaw برای این حالت، از جمله هنگام اجرای memory status --deep، کاوشگرهای آمادگی بردار معنایی یا نگهداری embedding در QMD را اجرا نمی‌کند؛ vsearch و query همچنان به آمادگی بردار و embeddingهای QMD نیاز دارند.

OpenClaw شکل‌های فعلی مجموعه QMD و پرس‌وجوی MCP را ترجیح می‌دهد، اما با آزمودن پرچم‌های الگوی مجموعه سازگار و نام‌های قدیمی‌تر ابزار MCP در صورت نیاز، نسخه‌های قدیمی‌تر QMD را هم فعال نگه می‌دارد. وقتی QMD پشتیبانی از چند فیلتر مجموعه را اعلام می‌کند، مجموعه‌های هم‌منبع با یک فرایند QMD جست‌وجو می‌شوند؛ ساخت‌های قدیمی‌تر QMD مسیر سازگاری به‌ازای هر مجموعه را نگه می‌دارند. هم‌منبع یعنی مجموعه‌های حافظه پایدار با هم گروه‌بندی می‌شوند، در حالی که مجموعه‌های رونوشت نشست در گروهی جدا می‌مانند تا تنوع منبع همچنان هر دو ورودی را داشته باشد.

{
  memory: {
    qmd: {
      scope: {
        default: "deny",
        rules: [{ action: "allow", match: { chatType: "direct" } }],
      },
    },
  },
}

بازآوری‌های راه‌اندازی QMD هنگام شروع Gateway از یک مسیر زیرفرایند تک‌مرحله‌ای استفاده می‌کنند. وقتی جست‌وجوی حافظه برای استفاده تعاملی باز می‌شود، مدیر بلندمدت QMD همچنان مالک ناظر فایل عادی و زمان‌سنج‌های بازه‌ای است.

# نمونه کامل QMD

{
  memory: {
    backend: "qmd",
    citations: "auto",
    qmd: {
      includeDefaultMemory: true,
      update: { interval: "5m", debounceMs: 15000 },
      limits: { maxResults: 6, timeoutMs: 4000 },
      scope: {
        default: "deny",
        rules: [{ action: "allow", match: { chatType: "direct" } }],
      },
      paths: [{ name: "docs", path: "~/notes", pattern: "**/*.md" }],
    },
  },
}

# Dreaming

Dreaming زیر plugins.entries.memory-core.config.dreaming پیکربندی می‌شود، نه زیر agents.defaults.memorySearch.

Dreaming به‌صورت یک پیمایش زمان‌بندی‌شده اجرا می‌شود و از فازهای داخلی سبک/عمیق/REM به‌عنوان جزئیات پیاده‌سازی استفاده می‌کند.

برای رفتار مفهومی و فرمان‌های اسلش، Dreaming را ببینید.

# تنظیمات کاربر

# نمونه

{
  plugins: {
    entries: {
      "memory-core": {
        subagent: {
          allowModelOverride: true,
          allowedModels: ["anthropic/claude-sonnet-4-6"],
        },
        config: {
          dreaming: {
            enabled: true,
            frequency: "0 3 * * *",
            model: "anthropic/claude-sonnet-4-6",
          },
        },
      },
    },
  },
}

# مرتبط

• مرجع پیکربندی
• نمای کلی حافظه
• جست‌وجوی حافظه