Workspace Local Retrieval

Build boundary-first local retrieval for OpenClaw with explicit corpora, deny-by-default agent access, separate memory layers, and a validated minimal demo p...

Security Scan

The skill's code, scripts, and runtime instructions align with the stated goal of bootstrapping a conservative, local-first workspace retrieval pattern; it requests no credentials and performs only local checks and template writes.

Purpose & Capability

Name/description match the included artifacts: a CLI wrapper, prereq checker, and bootstrapper that generate sanitized config templates for a local retrieval stack. Required capabilities (Python, Node, SQLite, optional local Ollama) are consistent with a local-first retrieval purpose.

Instruction Scope

SKILL.md and scripts constrain actions to: running prerequisite checks, writing template config files, and recommending next steps. The bootstrapper explicitly avoids network calls and does not index or scan user data. The CLI invokes only the included Python scripts and performs local file writes; no instructions ask the agent to read unrelated secrets or transmit data.

Install Mechanism

There is no registry install spec in the manifest (the skill is instruction/codeshipped), but package.json and bin/ provide an npm-friendly CLI. This is not harmful, but users should note that the npm-install claim in SKILL.md presumes publishing to npm; installing arbitrary packages from unknown registries has typical supply-chain risks.

Credentials

The skill declares no required env vars or credentials. The code respects optional local services (ollama) and uses PYTHON env var as an override for which Python executable to run — reasonable and proportionate for cross-platform scripts. No unrelated credentials are requested or used.

Persistence & Privilege

The skill does not request always:true or elevated platform privileges. It writes only template config files under the user-specified destination (refuses to overwrite without --force) and does not modify other skills or system-wide agent settings. Autonomous invocation is allowed by default (normal) but the skill's runtime behavior is local and conservative.

Assessment

This skill appears coherent and conservative, but review and confirm before running: (1) The bootstrapper will write template JSON files to the destination you provide — do not run with --force unless you want overwrites. (2) The skill does not auto-index or call the network, but the default backend template points to a local Ollama endpoint (127.0.0.1) — verify or change that before enabling embeddings. (3) If you plan to install the CLI via npm, prefer installing from a trusted package source; installing arbitrary global packages carries supply-chain risk. (4) Run the prereq checker first (workspace-local-retrieval check) and inspect generated config files before performing indexing or connecting any embedding backend. (5) If you need greater assurance, ask the publisher for an official release URL or audit the package that would appear on npm before installing.

Package retrieval as architecture, not ad-hoc glue.

This skill exists for a common failure mode in local RAG systems: indexing grows faster than boundary discipline. The result is usually a system that can sometimes retrieve relevant text, but cannot clearly answer:

• what should be searchable
• which agent should see which corpus
• what belongs in personal memory versus workspace knowledge
• how freshness should be maintained over time

Prefer this skill when the goal is workspace knowledge retrieval, not personal memory recall. Keep those layers separate.

Single-command npm install

This skill also ships as an npm-friendly CLI. Install it with one line (npm install -g workspace-local-retrieval) or run it on-demand via npx workspace-local-retrieval install. The CLI wraps the existing Python helpers (scripts/check_retrieval_prereqs.py + scripts/bootstrap_workspace_retrieval.py), so the install command performs a safety check, writes the retrieval/config templates, and hints at the next refresh/index steps. Run workspace-local-retrieval check anytime for a standalone prerequisite report.

Core workflow

0. Run a preflight gate before any retrieval work

   • Run scripts/check_retrieval_prereqs.py before bootstrap, indexing, embedding refresh, or search.
   • Classify findings into:
     • required: must exist before execution
     • recommended: may proceed with warning
     • optional: capability upgrade only
   • Treat missing required prerequisites as a hard stop.
   • Do not continue into retrieval execution when the environment is not ready.
   • Read references/dependencies-and-platforms.md when deciding what is required on the current OS.

1. Decide the boundary model first

   • Use built-in memory tools for personal continuity (MEMORY.md, memory/*.md).
   • Use this skill's retrieval pattern for workspace knowledge, docs, skills, plans, schemas, and agent-specific materials.
   • Do not merge personal notes into a general retrieval corpus unless the user explicitly wants that and understands the privacy tradeoff.

2. Design corpora before indexing

   • Split knowledge into small allowlisted corpora.
   • Prefer domain or workspace boundaries over one giant corpus.
   • Exclude runtime state, secrets, private notes, vector DB artifacts, build outputs, and caches.
   • Read references/privacy-and-boundaries.md before writing config.

3. Define agent access explicitly

   • Use deny-by-default agent retrieval policy.
   • Allow each agent to see only the corpora it needs.
   • Use separate memory-boundary rules for personal memory vs domain memory.
   • Read references/agent-scoping.md when creating agent rules.

4. Bootstrap templates safely

   • Run scripts/bootstrap_workspace_retrieval.py --dest <dir> to generate sanitized starter templates.
   • The script creates template config files only. It does not read external services, call the network, or ingest private data.
   • Read references/runtime-layout.md and references/dependencies-and-platforms.md before claiming the setup is runnable.
   • Run scripts/check_retrieval_prereqs.py before wiring indexing or embedding backends.

5. Implement retrieval entrypoints

   • Keep one stable wrapper for agent-facing search.
   • Make the wrapper responsible for corpus allowlist checks.
   • Keep indexing / embeddings / scoring internals behind the wrapper.
   • Read references/interface-contract.md for a recommended contract.

6. Add freshness + maintenance

   • Track corpus fingerprints or file signatures.
   • Prefer selective refresh when only a small set of files changed.
   • Fall back to full rebuild only when needed.
   • Read references/maintenance-patterns.md for a production-friendly approach.

7. Validate with smoke tests

   • Test at least:
     • one broad query
     • one corpus-specific query
     • one agent allowlist denial
     • one changed-file refresh path
   • Do not claim retrieval is ready because indexing succeeded once.

8. Handle missing prerequisites explicitly

   • If a required prerequisite is missing and the user has not authorized installation or environment changes:
     • stop
     • say the skill is currently unavailable
     • list the missing prerequisites
     • tell the user what must be installed or configured first
   • If a required prerequisite is missing and the user does want the environment prepared:
     • create a task plan first
     • make the plan OS-specific when needed
     • install or configure dependencies
     • update config and documentation to reflect the chosen backend and runtime
     • rerun scripts/check_retrieval_prereqs.py
     • continue only after the required checks pass
   • Use this rule consistently for macOS, Linux, and Windows. Do not pretend portability removes the need for explicit checks.

Recommended file layout

Use this skill as a pattern, not a rigid requirement.

retrieval/
  config/
    corpora.json
    agent_corpora.json
    agent_memory.json
    backend.json
  scripts/
    workspace_search.mjs
    build_index.py
    build_embeddings.mjs
    retrieval_status.py
    refresh_incremental.py
  indexes/
    workspace_retrieval.sqlite

If the workspace already has a retrieval system, adapt the layout instead of forcing a rewrite.

Defaults worth keeping

• local-first storage
• allowlisted corpora
• deny-by-default agent access
• personal memory separate from workspace retrieval
• minimal indexed file extensions
• explicit exclude globs
• incremental refresh before full rebuild
• one stable wrapper for agent-facing search

When to read references

• Read references/privacy-and-boundaries.md for safe corpus design and exclusions.
• Read references/agent-scoping.md when mapping corpora and memory roots to agents.
• Read references/interface-contract.md when building or reviewing the agent-facing search wrapper.
• Read references/maintenance-patterns.md when adding status checks, selective refresh, and smoke tests.
• Read references/example-templates.md when you need sanitized starter JSON examples.
• Read references/dependencies-and-platforms.md when the user wants concrete runtime dependencies, embedding backend choices, or cross-platform guidance.
• Read references/preflight-and-install-policy.md when deciding whether the skill is runnable now, blocked, or should first produce an installation task plan.
• Read references/runtime-layout.md when the user wants a more runnable implementation footprint.
• Read references/design-rationale.md when the user needs the architectural thesis, tradeoffs, or public-facing positioning.
• Read references/sanitized-demo.md when the user wants a safe walkthrough or publishable example.
• Read references/publish-readiness-checklist.md before packaging or publicly promoting the skill.

Practical guidance

• Prefer fewer, clearer corpora over many overlapping ones.
• Avoid indexing secrets, credentials, private journals, logs, and generated artifacts.
• If two agents need different trust levels, separate their corpora even if the docs overlap.
• If retrieval results look noisy, improve corpus design before tuning ranking weights.
• If privacy matters, treat boundary design as a first-class feature, not cleanup later.
• Treat prerequisite checks as part of the runtime contract, not as optional setup advice.
• The npm-friendly CLI is the simplest user entry point: workspace-local-retrieval install bootstraps the templates, workspace-local-retrieval check reports missing requirements, and both commands accept --dest, --workspace-root, and --force switches for customization.
• No required prerequisites, no execution.
• If installation is needed, prefer a short task plan over ad-hoc shell improvisation.
• After installation or config changes, rerun preflight checks before claiming the skill is ready.

Output expectations

When using this skill for a user request, produce some or all of the following depending on scope:

• sanitized corpus config
• agent allowlist config
• memory-boundary config
• search wrapper contract
• maintenance workflow
• smoke-test checklist
• packaging-ready skill contents when the user wants distribution