Rag Memory

Vector memory search and RAG setup. Use instead of loading full memory files. Handles first-time setup wizard, ongoing vector_search queries, Qdrant connecti...

Security Scan

The skill's purpose (RAG/vector search setup) matches many instructions, but there are multiple inconsistencies and missing pieces (missing files, mismatched variable names, undeclared runtime dependencies, and instructions that require root) that warrant caution before installing or running anything.

Purpose & Capability

The name and description (RAG / vector memory / Qdrant) align with the actions described (collect Qdrant, Postgres, Ollama endpoints; run syncs; add a vector_search tool). Asking for Qdrant host/key, Postgres DSN, and memory dir is proportionate for RAG setup. However, the SKILL.md assumes the presence of a separate codebase at /opt/sysclaw-rag (sync_to_qdrant.py, vector_search.js, systemd unit files) that is not included in this skill package — that mismatch is unexplained and meaningful.

Instruction Scope

The runtime instructions direct the agent to collect sensitive credentials, write /opt/sysclaw-rag/config.env, copy files into ~/.openclaw/tools, and install systemd units under /etc/systemd/system (sudo required). Those operations are plausible for installing a persistent sync service but the instructions reference many files that are not present in the package. There are also clear script/variable inconsistencies (e.g., using $KEY vs QDRANT_API_KEY, $DSN vs POSTGRES_DSN). The setup instructs overwriting config.env and copying unit files from /opt/sysclaw-rag — if those files are missing or untrusted, running the steps could break the system or expose credentials.

Install Mechanism

No install spec (instruction-only) is lowest-risk in distribution terms. But the instructions expect an existing /opt/sysclaw-rag installation and multiple support files (vector_search.js, sync_to_qdrant.py, systemd unit files) that are not included. That gap means the SKILL.md cannot be executed safely/fully from the provided package alone; the user would need to obtain the missing repository from somewhere else (trust implications).

Credentials

The skill prompts for sensitive credentials (QDRANT_API_KEY, POSTGRES_DSN, OLLAMA_HOST) which are reasonable for a RAG setup. However: (1) the skill does not declare any required env vars or a primary credential despite requiring these values; (2) the validation steps call psycopg2 via python but the skill does not declare Python package dependencies; (3) the config-writing step stores credentials at /opt/sysclaw-rag/config.env (root-owned path) — writing credentials there requires elevated privileges and centralizes secrets. These factors increase the risk surface and require user attention before providing secrets.

Persistence & Privilege

The skill instructs installing systemd units under /etc/systemd/system and enabling timers/watchers (persistent system services). That is a legitimate pattern for ongoing sync work but is a high-privilege, persistent change. The skill does not set always:true (so it won't auto-attach to every agent), which is good, but installing services requires sudo and will create a lasting system component — the user should review the actual unit files and sync scripts (which are not included) before enabling them.

What to consider before installing

Do not run the setup steps or hand over credentials until you have the full sysclaw-rag codebase and have reviewed the missing files (vector_search.js, sync_to_qdrant.py, and the systemd unit files). Specific things to check before proceeding: - Confirm source/trustworthiness of /opt/sysclaw-rag and obtain its repository or package (SKILL.md expects many files there but they are not included). - Inspect sync_to_qdrant.py and the systemd unit files to see what they do with credentials and network targets. - Fix the script issues: SKILL.md uses inconsistent variable names ($KEY vs QDRANT_API_KEY, $DSN vs POSTGRES_DSN). Validate and test commands manually. - Ensure required runtimes are present: Node.js is required to run the included JS scripts but is not listed in the skill's required binaries; python3 package psycopg2 is required for Postgres validation but not declared. Install and inspect these dependencies first. - Because the setup writes credentials to /opt/sysclaw-rag/config.env and installs systemd units, run those steps only after reviewing file contents and running them as a user who understands the implications — do not paste secrets into prompts until you trust the code. If you can provide the missing /opt/sysclaw-rag files or an install source (repo URL or package), I can re-evaluate and point out any malicious or unsafe code inside those files.

RAG Memory Skill

When to use this skill

• User asks to "set up RAG", "configure vector search", or "install sysclaw-rag" → run Setup Wizard
• Any memory or knowledge lookup → call vector_search tool instead of reading full files
• User asks to "resync memory" or results seem stale → run incremental or full sync
• Qdrant is unreachable → fall back gracefully (see references/operational.md)

---

Setup Wizard

Run this when vector_search tool is not yet configured or user requests setup. Read references/config-paths.md before starting — it lists every file and where it lives.

Step 1 — Detect environment

whoami          # capture as CURRENT_USER
hostname        # note the host for reference

Step 2 — Collect and validate credentials

Ask the user for each value one at a time. After each answer, validate before proceeding.

Value	Question to ask	Validation command
QDRANT_HOST	"What is the Qdrant URL? (e.g. https://qdrant.example.com)"	curl -sf $QDRANT_HOST/readyz → expect {"result":"ok"}
QDRANT_API_KEY	"What is the Qdrant API key? (press Enter to skip if none required)"	curl -sf -H "api-key: $KEY" $QDRANT_HOST/collections → expect 200 — skip if no key
OLLAMA_HOST	"What is the Ollama URL? (e.g. http://DESKTOP_IP:11434)"	curl -sf $OLLAMA_HOST/api/tags → check response contains nomic-embed-text
POSTGRES_DSN	"What is the Postgres DSN? (postgresql://user:pass@host/db)"	python3 -c "import psycopg2; psycopg2.connect('$DSN').close(); print('ok')"
MEMORY_DIR	"Where are your memory files? (default: ~/.openclaw/workspace/memory)"	ls $MEMORY_DIR → confirm .md files exist

If any validation fails, tell the user what failed and why, then ask them to correct it before continuing. Do not proceed past a failed validation.

Step 3 — Write config.env

Write to /opt/sysclaw-rag/config.env using the collected values. Use Python to write safely:

python3 << 'PYEOF'
import pathlib, uuid

# Preserve existing AGENT_UUID if already set (e.g. migrating from another machine)
existing = {}
cfg = pathlib.Path("/opt/sysclaw-rag/config.env")
if cfg.exists():
    for line in cfg.read_text().splitlines():
        if "=" in line:
            k, _, v = line.partition("=")
            existing[k.strip()] = v.strip()

agent_uuid = existing.get("AGENT_UUID") or str(uuid.uuid4())
print(f"AGENT_UUID: {agent_uuid}")

values = {
    "AGENT_UUID": agent_uuid,
    "QDRANT_HOST": "...",
    "QDRANT_API_KEY": "",
    "OLLAMA_HOST": "...",
    "OLLAMA_EMBED_MODEL": "nomic-embed-text",
    "POSTGRES_DSN": "...",
    "MEMORY_DIR": "...",
    "SKILL_DIRS": "",
    "CHUNK_SIZE": "400",
    "CHUNK_OVERLAP": "50",
    "TOP_K_DEFAULT": "5",
    "SYNC_BATCH_SIZE": "50",
}
cfg.write_text("\n".join(f"{k}={v}" for k, v in values.items()) + "\n")
print("config.env written")
PYEOF

Step 4 — Copy vector_search tool

mkdir -p ~/.openclaw/tools
cp /opt/sysclaw-rag/vector_search.js ~/.openclaw/tools/

Step 5 — Verify openclaw.json is valid

The vector_search tool is auto-discovered from ~/.openclaw/tools/ — no config registration needed. Do NOT add tools.vector_search, agents.defaults.model.fallback, or a root-level providers key to openclaw.json. These are unrecognized by the current OpenClaw config validator and will break the gateway.

Simply confirm the file is valid JSON and the gateway can start:

systemctl --user status openclaw-gateway.service

If the gateway reports Invalid config, check for and remove any of the above keys.

Step 6 — Install systemd units

Note: writing to /etc/systemd/system/ requires sudo. Run these commands as root or with sudo.

CURRENT_USER=$(whoami)

# Replace YOUR_USER placeholder in all four unit files
for f in sysclaw-rag-sync.service sysclaw-rag-watch.path sysclaw-rag-watch.service; do
    sudo sed "s/YOUR_USER/$CURRENT_USER/g" /opt/sysclaw-rag/$f \
        > /etc/systemd/system/$f
done

# Timer has no YOUR_USER but copy it anyway
sudo cp /opt/sysclaw-rag/sysclaw-rag-sync.timer /etc/systemd/system/

sudo systemctl daemon-reload
systemctl enable --now sysclaw-rag-sync.timer
systemctl enable --now sysclaw-rag-watch.path

Step 7 — Run initial sync and verify

cd /opt/sysclaw-rag
venv/bin/python sync_to_qdrant.py --full

Then call vector_search with query: "test" to confirm end-to-end connectivity. Report results to user.

Step 8 — Restart OpenClaw

systemctl --user restart openclaw-gateway.service

Inform user that setup is complete and vector_search is now active.

---

Ongoing sync management

• Incremental sync (automatic via systemd watcher) — runs whenever a .md file in ~/.openclaw/workspace/memory/ changes
• Nightly full sync (automatic via systemd timer) — runs at 03:00
• Manual resync — if user reports stale results: cd /opt/sysclaw-rag && venv/bin/python sync_to_qdrant.py --full
• Single file sync — after editing one file: venv/bin/python sync_to_qdrant.py --file ~/.openclaw/workspace/memory/MEMORY.md

---

Operational usage

See references/operational.md for full guidance on when and how to use vector_search during normal operations.