Agent-Scoped Local Retrieval

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:

1. Enter the skill folder:

   cd workspace-local-retrieval
   

2. Check prerequisites:

   python3 scripts/check_retrieval_prereqs.py
   

3. 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
     

4. 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.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