# Agent-Scoped Local Retrieval

Adopt this skill: https://proskills.md/skills/other/ys-c-23-workspace-local-retrieval-skill-workspace-local-retrieval

Page: https://proskills.md/skills/other/ys-c-23-workspace-local-retrieval-skill-workspace-local-retrieval
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: workspace-local-retrieval/SKILL.md
size: 7077
upstream: https://github.com/ys-c-23/workspace-local-retrieval-skill/blob/main/workspace-local-retrieval/SKILL.md

````text
---
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 distribution
````

## File: README.md
upstream: https://github.com/ys-c-23/workspace-local-retrieval-skill/blob/main/README.md

````text
# 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

```text
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:

1. Enter the skill folder:
   ```bash
   cd workspace-local-retrieval
   ```
2. Check prerequisites:
   ```bash
   python3 scripts/check_retrieval_prereqs.py
   ```
3. If dependencies are missing:
   - macOS:
     ```bash
     bash scripts/install_prereqs_mac.sh
     ```
   - Linux:
     ```bash
     bash scripts/install_prereqs_linux.sh
     ```
   - Windows (PowerShell):
     ```powershell
     powershell -ExecutionPolicy Bypass -File .\scripts\install_prereqs_windows.ps1
     ```
4. Run the minimal closed-loop demo:
   ```bash
   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.py` to generate starter config
- `references/quickstart-real-workspace.md` for 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

1. Run the prerequisite check first.
2. 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.
3. Bootstrap sanitized retrieval config templates.
4. Define explicit corpora.
5. Define deny-by-default agent access.
6. Keep personal memory and workspace retrieval as separate layers.
7. Add a stable retrieval wrapper.
8. Add freshness checks and selective refresh.
9. 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
````
