⏳ This skill is pending AI review.
Scores will appear once the review pipeline completes.
Agent-Scoped 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 path.
Choose how to use this skill
You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.
1. Native installer
This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.
Do not guess an installer command or replace an existing version without reviewing the diff.
2. Complete package recommended
Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.
No complete ProSkills package is published for this listing yet.3. Prompt-only
Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.
Need only the instruction file?
Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.
No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.
// RATINGS
Not yet listed on ClawHub or SkillsMP
// README
Agent-Scoped Local Retrieval
A boundary-first local retrieval skill for OpenClaw workspaces.
This repository packages a reusable local-first retrieval pattern for multi-agent environments with:
- explicit corpus boundaries
- deny-by-default agent access
- prerequisite gating before runtime execution
- maintenance-aware refresh behavior
- explicit maturity labels for honest validation claims
It includes a validated minimal demo path and a bootstrap pattern for adapting the architecture to a real OpenClaw workspace, without claiming turnkey production retrieval for arbitrary environments.
Why this exists
Many local RAG setups start with one simple idea: index everything and add search.
That works for quick demos, but it breaks down in longer-running workspaces. The first problems are often not ranking quality. They are:
- personal memory mixed with reusable workspace knowledge
- unclear retrieval boundaries
- agents getting broader access than they should
- noisy recall from over-broad indexing
- refresh workflows that default to blind full rebuilds
- runtime dependencies discovered too late, after execution has already started failing
- maturity claims that outrun what has actually been tested
workspace-local-retrieval packages a different default.
Core ideas
- Separate personal memory from workspace retrieval
- Use allowlisted corpora instead of indexing everything
- Enforce deny-by-default access per agent
- Keep one stable retrieval interface for callers
- Treat maintenance and selective refresh as part of the design
- Gate execution on prerequisite checks
- Classify maturity honestly using explicit validation rules
The emphasis is not only retrieval quality. It is retrieval architecture, runtime discipline, and validation honesty.
What the skill includes
- a workflow-oriented
SKILL.md - sanitized starter templates for corpora, agent allowlists, memory boundaries, and backend config
- reference docs for:
- privacy and boundaries
- agent scoping
- interface contracts
- maintenance patterns
- dependency and platform guidance
- preflight and install policy
- quickstart guidance for adapting the pattern to a real workspace
- validation contract
- anti-overclaim guidance
- design rationale
- publish readiness
- a conservative bootstrap script that generates starter config without ingesting private data automatically
- a runnable prerequisite check script for Python / Node / SQLite / FTS5 / embedding-backend readiness
- a sanitized demo corpus plus minimal index/search/smoke-test scripts for a closed-loop proof path
- a sanitized demo walkthrough for public explanation and validation
Who this is for
This skill is useful if you are building:
- local AI assistants
- multi-agent workspaces
- privacy-sensitive local RAG systems
- agent infrastructure with scoped retrieval access
- long-running retrieval workflows that need maintenance discipline
What this skill is not
This is not:
- a hosted vector database
- a turnkey enterprise retrieval platform
- a benchmark package for ranking quality
- a substitute for careful corpus design
- a fully validated closed-loop retrieval system by default
It is a reusable architectural pattern and starter kit.
Maturity labels
Use these labels honestly:
- architecture-only: boundaries, templates, and contracts exist, but no real retrieval loop has been proven
- minimally runnable: a safe demo path can ingest a small corpus, build an index, and answer at least one query
- fully validated: the minimal closed loop exists and the validation contract passes
Do not call the repo fully validated, end-to-end, production-ready, or plug-and-play unless the actual evidence supports that claim.
Repository contents
workspace-local-retrieval/
SKILL.md
assets/
demo-corpus/
references/
agent-scoping.md
anti-overclaim.md
dependencies-and-platforms.md
design-rationale.md
example-templates.md
interface-contract.md
maintenance-patterns.md
minimal-e2e-demo.md
preflight-and-install-policy.md
privacy-and-boundaries.md
publish-readiness-checklist.md
runtime-layout.md
sanitized-demo.md
validation-contract.md
scripts/
bootstrap_workspace_retrieval.py
build_minimal_index.py
check_retrieval_prereqs.py
install_prereqs_linux.sh
install_prereqs_mac.sh
install_prereqs_windows.ps1
run_minimal_smoke_tests.py
search_minimal_index.py
setup_demo.sh
What works today
Today this repository can help a user:
- check local prerequisites
- install baseline prerequisites on macOS and Linux with helper scripts
- install baseline prerequisites on Windows via a winget-based PowerShell helper
- run a validated minimal retrieval demo
- bootstrap sanitized starter config for adapting the pattern to a real workspace
A safe public summary is:
This repo includes a validated minimal demo path and a bootstrap pattern for adapting the retrieval architecture to a real OpenClaw workspace.
What it does not claim today:
- turnkey production retrieval for arbitrary workspaces
- fully automated semantic retrieval setup
- zero-judgment corpus design or policy design
5-minute runnable path
For a technically comfortable first-time user, the fastest path is:
- Enter the skill folder:
cd workspace-local-retrieval - Check prerequisites:
python3 scripts/check_retrieval_prereqs.py - If dependencies are missing:
- macOS:
bash scripts/install_prereqs_mac.sh - Linux:
bash scripts/install_prereqs_linux.sh - Windows (PowerShell):
powershell -ExecutionPolicy Bypass -File .\scripts\install_prereqs_windows.ps1
- macOS:
- Run the minimal closed-loop demo:
bash scripts/setup_demo.sh
This path validates a small local retrieval system with:
- prerequisite gating
- bootstrap-ready config patterns
- SQLite FTS5 indexing
- scoped search
- smoke-test coverage
Adapting to a real workspace
After the demo path passes, the next step is to adapt the pattern to your own workspace.
Use:
scripts/bootstrap_workspace_retrieval.pyto generate starter configreferences/quickstart-real-workspace.mdfor the first real workspace path
The recommended approach is:
- start with a narrow lexical baseline
- define corpora before indexing
- keep deny-by-default agent access
- validate one real workflow before broadening scope
Suggested usage
- Run the prerequisite check first.
- If required dependencies are missing, stop and either:
- report the skill as currently unavailable, or
- create an OS-aware install plan if environment prep is allowed.
- Bootstrap sanitized retrieval config templates.
- Define explicit corpora.
- Define deny-by-default agent access.
- Keep personal memory and workspace retrieval as separate layers.
- Add a stable retrieval wrapper.
- Add freshness checks and selective refresh.
- Validate using the maturity labels and validation contract.
Why the public version is sanitized
This repository is intentionally generalized.
It does not include:
- private workspace paths
- live user data
- private memory files
- credentials or tokens
- generated indexes or embeddings
- environment-specific runtime state
The goal is to publish the pattern, not leak the original workspace.
Publishing
For ClawHub distribution, package and upload the .skill artifact.
For GitHub distribution, publish the skill folder plus a small amount of explanatory material such as this README and launch copy.
License
This project is licensed under the MIT License. See LICENSE.
Contact / discussion
If you are working on local-first assistants, agent infrastructure, retrieval governance, or privacy-aware multi-agent systems, feel free to adapt the pattern and compare notes
// HOW IT'S BUILT
// FILES
2 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.
workspace-local-retrieval/SKILL.md6.9 KBupstream ↗
--- name: Agent-Scoped Local Retrieval description: Build boundary-first local retrieval for OpenClaw with explicit corpora, deny-by-default agent access, separate memory layers, and a validated minimal demo path. --- # Workspace Local Retrieval 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 - what has actually been validated versus merely sketched Prefer this skill when the goal is **workspace knowledge retrieval**, not personal memory recall. Keep those layers separate. ## Core workflow 1. **Run a preflight gate before any retrieval work** - Run `scripts/check_retrieval_prereqs.py` before bootstrap, indexing, embedding refresh, or search. - Treat missing required prerequisites as a hard stop. - If the user wants direct setup help, use `scripts/install_prereqs_mac.sh` on macOS or `scripts/install_prereqs_linux.sh` on Linux as a first-pass installer, then rerun preflight. - Read `references/dependencies-and-platforms.md` when deciding what is required on the current OS. - Read `references/preflight-and-install-policy.md` when deciding whether to stop, warn, or produce an installation plan. 2. **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. - Read `references/privacy-and-boundaries.md` before writing corpus config. 3. **Design corpora and agent access explicitly** - Split knowledge into small allowlisted corpora. - Use deny-by-default agent retrieval policy. - Keep separate memory-boundary rules for personal memory vs domain memory. - Read `references/agent-scoping.md` when mapping corpora and memory roots to agents. 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. - For first-run validation, use `scripts/setup_demo.sh` to execute the minimal demo path before adapting the pattern to a real workspace. - Read `references/runtime-layout.md` before claiming the setup is runnable. 5. **Implement one stable retrieval entrypoint** - Keep one wrapper responsible for agent-facing search and corpus allowlist checks. - Keep indexing, embeddings, and scoring internals behind the wrapper. - Read `references/interface-contract.md` for the recommended search-wrapper contract. 6. **Add maintenance-aware refresh behavior** - 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 before making maturity claims** - Do not claim retrieval is ready because indexing succeeded once. - Read `references/validation-contract.md` to classify the result as `architecture-only`, `minimally runnable`, or `fully validated`. - Read `references/anti-overclaim.md` before writing publish-facing or user-facing maturity claims. - When the user wants proof of a runnable closed loop, read `references/minimal-e2e-demo.md` and run the demo scripts rather than describing a hypothetical future validation plan. ## Hard truth rules - No required prerequisites, no execution. - No real closed loop, no `end-to-end` claim. - No smoke-test suite, no `fully validated` claim. - No reproducible evidence, no strong marketing language. - If uncertain, downgrade the maturity label rather than stretch it. ## Recommended file layout Use this skill as a pattern, not a rigid requirement. ```text 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 - validation before maturity claims ## 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/quickstart-real-workspace.md` when the user wants to move from the demo path into a real workspace setup. - 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/validation-contract.md` when deciding what completion level has actually been achieved. - Read `references/minimal-e2e-demo.md` when the user wants a safe runnable proof path. - Read `references/anti-overclaim.md` before packaging or publicly promoting the skill. - Read `references/publish-readiness-checklist.md` before packaging or publicly promoting the skill. ## 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 - validation report with an honest maturity label - packaging-ready skill contents when the user wants distributionREADME.mdupstream ↗
Contents are not inlined in the catalog. Open the upstream file.
Plain-text copy, no login: /skill-bundles/ys-c-23-workspace-local-retrieval-skill-workspace-local-retrieval.md