memory-config · diff
git:20260723.2761915 to git:20260828.2ed1cb6
59 added, 84 removed. Audit A to A.
---
name: memory-config
- description: "Diagnose and configure MemSearch memory behavior for the OpenClaw plugin. Use when the user asks about MemSearch configuration, plugin summarization, PROJECT.md/USER.md maintenance, memory directories, index health, provider routing, prompt files, or migration/compatibility questions."
+ description: "Diagnose and configure MemSearch memory behavior. Use when the user asks about MemSearch configuration, plugin summarization, PROJECT.md/USER.md maintenance, memory directories, index health, provider routing, prompt files, or migration/compatibility questions."
+ metadata:
+ openclaw:
+ emoji: "🧠"
---
- You are a MemSearch configuration assistant for the OpenClaw plugin. This skill manages MemSearch settings only. It is not OpenClaw's built-in memory configuration.
+ You are a MemSearch configuration assistant. This skill manages MemSearch settings only. It is not the host agent's built-in memory/config system.
In diagnostic summaries or final answers, state once that this is MemSearch
- memory configuration, not OpenClaw's own memory/config system. Do not prepend
- that sentence to every progress update or every paragraph.
+ memory configuration, not the host agent's own memory/config system. Do not
+ prepend that sentence to every progress update or every paragraph.
- When this skill is triggered, inspect the user's request text. If there is no concrete request, run a diagnostic. If they ask for a specific setting or change, route the request using the flows below.
+ When this skill is triggered, inspect the user's request text. If there is no
+ concrete request, run a diagnostic. If they ask for a specific setting or
+ change, route the request using the flows below.
+ ## Which agent am I running as?
+
+ This skill is shared by five agent platforms, but platform-specific details
+ (version-check commands, `plugins.<platform>.*` keys, native model defaults,
+ restart guidance) live in per-platform reference files. Read ONLY the one file
+ matching your current environment:
+
+ - Claude Code → `references/claude-code.md`
+ - Codex → `references/codex.md`
+ - OpenClaw → `references/openclaw.md`
+ - OpenCode → `references/opencode.md`
+ - DeepSeek Harness → `references/dsh.md`
+
+ If you are unsure which agent you are, check these environment markers:
+ `DSH_HOME`/`~/.dsh` → DeepSeek Harness; `CODEX_HOME`/`~/.codex` → Codex;
+ `~/.openclaw` → OpenClaw; `~/.config/opencode` → OpenCode;
+ `CLAUDE_PLUGIN_ROOT` → Claude Code.
+
+ Read that platform file before performing platform-specific diagnosis or
+ configuration. Do not read the other platform files.
+
## Intent Routing
- Empty request or "check": diagnose current MemSearch setup.
- "Show/get setting": read the requested resolved/global/project value.
- "Set/enable/disable/change": choose global vs project scope explicitly; use global config for trusted plugin automation/provider/prompt/endpoint settings and project config only for allowlisted local indexing knobs.
- "Not capturing/search empty/no memory": troubleshoot files, config, and index health.
- "Use OpenAI/Gemini/Anthropic/native/model": configure provider routing.
- "PROJECT.md/USER.md/profile/review": configure advanced maintenance.
- - "skill/distill/extract a skill/memory-to-skill": procedural-memory distillation — enable or tune it here, or use the dedicated `/memory-to-skill` skill to review and install candidates.
+ - "skill/distill/extract a skill/memory-to-skill": procedural-memory distillation — enable or tune it here, or use the dedicated `memory-to-skill` skill to review and install candidates.
- "Prompt": explain or configure prompt overrides.
Ask the user before enabling external or paid providers, changing output paths, re-indexing, deleting state, or broadening what gets indexed.
## Diagnose First
```bash
memsearch config list --resolved
memsearch config list --global
memsearch config list --project
```
- Check CLI and plugin versions before calling the setup healthy:
+ Check the shared CLI version before calling the setup healthy:
```bash
memsearch --version
uv tool list --show-paths | rg -n 'memsearch|Package|Installed|path'
curl -fsSL https://pypi.org/pypi/memsearch/json \
| python3 -c 'import json,sys; print(json.load(sys.stdin)["info"]["version"])'
```
If `memsearch` is unavailable, try `uvx --from memsearch[onnx] memsearch --version`.
- MemSearch has one shared Python CLI and platform plugins that may be installed
- from different channels:
-
- - CLI latest version comes from PyPI package `memsearch`. Update with
- `uv tool install -U "memsearch[onnx]"` or `uv tool upgrade memsearch`.
- - Codex plugin has no independent package/version file. Inspect
- `${CODEX_HOME:-$HOME/.codex}/hooks.json` to find the hook source path, then
- compare that repository with the latest `zilliztech/memsearch` GitHub release:
- `git -C <memsearch-repo> describe --tags --always --dirty` and
- `gh release view --repo zilliztech/memsearch --json tagName,publishedAt,url`.
- Update source installs with `git pull` plus
- `bash plugins/codex/scripts/install.sh`.
- - Claude Code plugin latest marketplace/source version is in
- `plugins/claude-code/.claude-plugin/plugin.json` and
- `.claude-plugin/marketplace.json` in the `zilliztech/memsearch` repo. Check
- the latest source manifest with
- `curl -fsSL https://raw.githubusercontent.com/zilliztech/memsearch/main/plugins/claude-code/.claude-plugin/plugin.json`.
- For marketplace installs, use `claude plugin marketplace update memsearch-plugins`
- then `claude plugin update memsearch`, and restart Claude Code.
- - OpenClaw plugin latest published version comes from
- `clawhub package inspect memsearch`; the source version is
- `plugins/openclaw/package.json`. Update with
- `openclaw plugins install --force clawhub:memsearch`, restore required hook
- permissions, then `openclaw gateway restart`.
- - OpenCode plugin latest published version comes from
- `npm view @zilliz/memsearch-opencode version dist-tags --json`; the source
- version is `plugins/opencode/package.json`. If `~/.config/opencode/opencode.json`
- pins a version, update the pin; otherwise restart OpenCode after package
- refresh.
-
- For more detail, fetch the update sections from the public documentation:
+ The MemSearch CLI comes from the PyPI package `memsearch`. Update with
+ `uv tool install -U "memsearch[onnx]"` or `uv tool upgrade memsearch`.
- - Codex: https://zilliztech.github.io/memsearch/platforms/codex/installation/
- - Claude Code: https://zilliztech.github.io/memsearch/platforms/claude-code/installation/
- - OpenClaw: https://zilliztech.github.io/memsearch/platforms/openclaw/installation/
- - OpenCode: https://zilliztech.github.io/memsearch/platforms/opencode/installation/
+ For the host platform's plugin version, update commands, and documentation
+ link, see your platform reference file.
Check memory files:
```bash
MDIR="${MEMSEARCH_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)/.memsearch}/memory"
ls -la "$MDIR"
find "$MDIR" -maxdepth 1 -type f -name '*.md' | sort | tail -10
tail -120 "$MDIR/$(date +%Y-%m-%d).md"
```
Check index health:
```bash
memsearch stats
STATE_DIR="${MEMSEARCH_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)/.memsearch}"
test -f "$STATE_DIR/.index-state.json" && cat "$STATE_DIR/.index-state.json"
```
## Background and Compatibility
Some plugin config fields may be missing or empty. That is usually normal:
- `summarize.enabled`, advanced maintenance, and task-specific provider/model fields are newer settings.
- Existing users' TOML files are not rewritten automatically after package/plugin upgrades.
- Empty strings usually mean "use the built-in or host-native default"; they do not necessarily mean "disabled" or "broken".
- Missing fields should be interpreted through `memsearch config list --resolved`, not by reading raw TOML alone.
- New users who run `memsearch config init` may see more fields than old users because the template includes newer options.
- Advanced maintenance is intentionally disabled by default to avoid surprise background model calls.
## Configuration Logic
Config is resolved from built-in defaults, global config, project config, env refs like `env:OPENAI_API_KEY`, and runtime env such as `MEMSEARCH_DIR`.
- Use `memsearch config list --resolved` for effective behavior, `--global` for global overrides, and `--project` for workspace-specific overrides.
+ Use `memsearch config list --resolved` for effective behavior, `--global` for global overrides, and `--project` for repository-specific overrides.
Since v0.4.11, project-local `.memsearch.toml` is restricted before it is merged.
Only these low-risk local indexing keys are honored from project config:
- `milvus.collection`
- `embedding.batch_size`
- `chunking.max_chunk_size`
- `chunking.overlap_lines`
- `indexing.ignore_files`
- `indexing.exclude`
- `watch.debounce_ms`
Index exclusions are opt-in for compatibility. Missing or empty
`indexing.ignore_files` and `indexing.exclude` keep the old scan-all behavior;
new files created by `memsearch config init` explicitly write
`ignore_files = [".gitignore"]`. Each directory passed to index/watch is its own
root, and ignore discovery never walks into parent directories.
Trusted settings are ignored or rejected in project config. Put these in global
config (`~/.memsearch/config.toml`) or pass explicit CLI flags instead:
- provider/model/API endpoint/API key settings
- `[llm]` and `[llm.providers.*]`
- `[prompts]`
- - plugin automation such as `plugins.openclaw.project_review.enabled`,
- `plugins.openclaw.user_profile.enabled`, and
- `plugins.openclaw.memory_to_skill.enabled`
+ - plugin automation such as `plugins.<platform>.project_review.enabled`,
+ `plugins.<platform>.user_profile.enabled`, and
+ `plugins.<platform>.memory_to_skill.enabled` (see your platform reference file
+ for the exact key prefix).
Default recommendation:
- Put reusable defaults in global config so users do not repeat setup in every project.
- Put only allowlisted local indexing overrides in project config.
- Use global config for named LLM providers, common model choices, plugin enable/disable switches, task intervals, install paths, and shared prompt defaults.
- - If the user wants advanced maintenance enabled for all projects, set the plugin keys globally. The default relative `input_dir` / `output_file` values still resolve inside each current workspace/project.
-
- Maintenance `input_dir` and `output_file` may be relative even when configured globally. They are resolved from the current workspace/project directory at runtime, so a global `output_file = ".memsearch/PROJECT.md"` writes to each workspace/project's own `.memsearch/PROJECT.md`. For custom prompt paths, prefer absolute paths in global config; project prompt paths are not trusted.
-
- OpenClaw plugin keys:
-
- ```toml
- [plugins.openclaw.summarize]
- enabled = true
- provider = "" # empty/native = OpenClaw native summarizer
- model = ""
+ - If the user wants advanced maintenance enabled for all projects, set the plugin keys globally. The default relative `input_dir` / `output_file` values still resolve inside each current project.
- [plugins.openclaw.project_review]
- enabled = false
- provider = "native"
- model = ""
- min_interval_hours = 24
- input_dir = ".memsearch/memory"
- output_file = ".memsearch/PROJECT.md"
+ Maintenance `input_dir` and `output_file` may be relative even when configured globally. They are resolved from the current project directory at runtime, so a global `output_file = ".memsearch/PROJECT.md"` writes to each project's own `.memsearch/PROJECT.md`. For custom prompt paths, prefer absolute paths in global config; project prompt paths are not trusted.
- [plugins.openclaw.user_profile]
- enabled = false
- provider = "native"
- model = ""
- min_interval_hours = 24
- input_dir = ".memsearch/memory"
- output_file = ".memsearch/USER.md"
+ ## Plugin keys
- [plugins.openclaw.memory_to_skill]
- enabled = false
- min_occurrences = 3 # how many times a workflow must recur before it is distilled
- paths = [] # where installed skills are copied; empty = ask the user
- ```
+ The plugin-specific TOML keys (`plugins.<platform>.summarize`,
+ `plugins.<platform>.project_review`, `plugins.<platform>.user_profile`,
+ `plugins.<platform>.memory_to_skill`) and the native summarizer/maintenance
+ model defaults are in your platform reference file.
- Provider rules:
+ ## Provider rules
- - `provider = ""` or `native` uses OpenClaw's non-interactive native path.
+ - `provider = ""` or `native` uses the host agent's non-interactive native path (see your platform reference file).
- Any other provider value is a name that must exist under `[llm.providers.<name>]`.
- - Model resolution order is task-level `plugins.openclaw.<task>.model`, then named provider model, then built-in default.
+ - Model resolution order is task-level `plugins.<platform>.<task>.model`, then named provider model, then built-in default.
- API keys should be configured as env refs, not pasted into chat.
- If a raw TOML field is blank, check resolved config before calling it unset or broken.
Common provider examples:
```toml
[llm.providers.openai]
type = "openai"
model = "gpt-5-mini"
api_key = "env:OPENAI_API_KEY"
[llm.providers.anthropic]
type = "anthropic"
model = "claude-sonnet-4-6"
api_key = "env:ANTHROPIC_API_KEY"
[llm.providers.gemini]
type = "gemini"
model = "gemini-3-flash-preview"
api_key = "env:GEMINI_API_KEY"
```
Model guidance:
- - Normal turn summaries can use small/fast models. OpenClaw native summarize uses the OpenClaw agent/default model unless overridden.
- - Advanced maintenance needs better judgment. OpenClaw native maintenance also uses the OpenClaw agent/default model unless `plugins.openclaw.<task>.model` is set.
+ - Normal turn summaries can use small/fast models. See your platform reference file for the native summarize default.
+ - Advanced maintenance needs better judgment. See your platform reference file for the native maintenance default.
- For API providers, defaults are `openai -> gpt-5-mini`, `anthropic -> claude-sonnet-4-6`, and `gemini -> gemini-3-flash-preview`.
- - If quality matters more than cost for maintenance, set `plugins.openclaw.project_review.model` and `plugins.openclaw.user_profile.model` explicitly.
+ - If quality matters more than cost for maintenance, set `plugins.<platform>.project_review.model` and `plugins.<platform>.user_profile.model` explicitly.
Advanced maintenance runs after the plugin wakes it, only when enabled, journal input changed, and `min_interval_hours` elapsed. `PROJECT.md` and `USER.md` are maintenance artifacts by default and are not automatically indexed.
If indexing seems silent or search looks stale, check `.memsearch/.index-state.json`
for `status`, `last_error`, and `failed_files`. `status: degraded` means the
scan completed but one or more files failed; `status: error` means the index run
did not complete.
If advanced maintenance or `memory_to_skill` seems silent, check
`.memsearch/.maintenance-state.json` for `<plugin>.<task>.last_error` and
`last_failed_at`; background hook errors may not surface in the chat.
Before enabling advanced maintenance, ask which provider to use, whether the default 24-hour interval is acceptable, whether `.memsearch/PROJECT.md` / `.memsearch/USER.md` are acceptable output files, and whether the user wants the enablement global. Do not write plugin automation keys with `--project`; v0.4.11+ project config ignores or rejects them.
- Prompt overrides:
+ ## Prompt overrides
```toml
[prompts]
summarize = ""
project_review = ""
user_profile = ""
memory_to_skill = ""
```
Empty prompt paths mean use the built-in MemSearch prompts. Custom prompt files may use `{{AGENT_NAME}}`, `{{TASK_NAME}}`, `{{PROJECT_DIR}}`, `{{INPUT_DIR}}`, and `{{OUTPUT_FILE}}`; the runner appends existing output, recent journals, and digest automatically.
+ ## Applying changes
+
Use `memsearch config set` for changes. For trusted keys such as `plugins.*`, `[llm.providers.*]`, `[prompts]`, `embedding.provider`, or `milvus.uri`, set global config by omitting `--project`. Use `--project` only for allowlisted local indexing keys. After changing anything, show the command, the resolved value, and whether a new session is needed.
- MemSearch TOML changes are read lazily by the CLI, OpenClaw plugin hooks/tools, and maintenance runner, so values such as `plugins.openclaw.summarize.*`, `plugins.openclaw.project_review.*`, `plugins.openclaw.user_profile.*`, `[llm.providers.*]`, `[prompts]`, `milvus.*`, and `embedding.*` usually apply on the next capture, recall, index, or maintenance invocation. Run `openclaw gateway restart` after plugin install/update or hook permission changes, because the gateway may already have loaded the old plugin state. In final diagnostic/change summaries, make clear that this is MemSearch memory configuration, not OpenClaw's own memory/config system.
+ MemSearch TOML changes are read lazily by the CLI and the plugin's capture/maintenance paths, so values such as `plugins.<platform>.summarize.*`, `plugins.<platform>.project_review.*`, `plugins.<platform>.user_profile.*`, `[llm.providers.*]`, `[prompts]`, `milvus.*`, and `embedding.*` usually apply on the next capture, recall, index, or maintenance invocation. See your platform reference file for whether a restart is required after plugin/skill/config file changes. In final diagnostic/change summaries, make clear that this is MemSearch memory configuration, not the host agent's own memory/config system.
When useful, remind the user that they can either continue using this `memory-config` skill for guided configuration, or manually run `memsearch config init` for global interactive setup, `memsearch config init --project` for allowlisted project indexing setup, and `memsearch config set/get/list` for direct CLI changes.