Document research — private RAG over a PDF corpus

1Install enclawed-oss

curl -fsSL --proto '=https' --tlsv1.2 https://enclawed.com/install.sh | bash

enclawed --version

2Configure memory-lancedb

The shipped config block matches the keys the extension validates in extensions/memory-lancedb/config.ts:

// ~/.enclawed/enclawed.json
{
  "memory": {
    "embedding": {
      "apiKey":  "${OPENAI_API_KEY}",        // ${ENV} interpolation is supported
      "model":   "text-embedding-3-small",   // or set "dimensions" for a custom model
      "baseUrl": "http://127.0.0.1:11434/v1" // point at your local OpenAI-compatible server
    },
    "dbPath":       "~/.enclawed/memory/lancedb",
    "autoRecall":   true,
    "autoCapture":  false,
    "captureMaxChars": 500
  }
}

The egress allowlist (loopback-only for this scenario) is set at bootstrap time, the same way the other tutorials show:

// bootstrap-shim.ts
import { bootstrapEnclawed } from "enclawed/bootstrap";
import { createPolicy } from "enclawed/policy";
import { makeLabel, LEVEL } from "enclawed/classification";

await bootstrapEnclawed({
  policy: createPolicy({
    enforceAllowlists: true,
    allowedHosts:      ["127.0.0.1", "::1", "localhost"],
    maxOutputClearance: makeLabel({ level: LEVEL.UNCLASSIFIED }),
    defaultDataLabel:   makeLabel({ level: LEVEL.UNCLASSIFIED }),
  }),
});

With allowedHosts set to loopback only, the egress guard drops any outbound packet to anything else.

3Ingest documents into memory

The shipped tool surface is memory_store, exposed to the agent as a model-callable tool. A small host script runs document-extract over each PDF, then calls memory_store per chunk — or you can have the agent itself drive both tools.

// ingest.ts — called from your host process, with the
// document-extract extractor and the memory-lancedb tools loaded.
import { extractDocument } from "openclaw/plugin-sdk/document-extractor";
import { invokeTool } from "openclaw/plugin-sdk/runtime";       // host facade

const allowedSources = [resolve(homedir(), "Documents", "research-corpus")];

for (const pdf of await listPdfs(allowedSources)) {
  const extracted = await extractDocument({ filePath: pdf });
  for (const chunk of chunkPages(extracted, { size: 1100, overlap: 120 })) {
    await invokeTool("memory_store", {
      text:       chunk.text,
      importance: 0.8,
      category:   "fact",
    });
  }
}

The plugin exposes memory_ingest, memory_search, and memory_get as agent tools whenever memory.corpora[] is declared in the host config — each takes a corpus id and looks up the matching path, chunkSize, and chunkOverlap from the declaration. Use these in the system prompt to scope retrieval to a specific corpus.

4Verify the policy in effect

There is no shipped enclawed policy show command. To confirm what the bootstrap actually loaded, inspect the first audit line:

head -n 1 ~/.enclawed/audit.jsonl | jq '. | {ts, type, payload}'

# Sample:
# { "ts": 1716210000000,
#   "type": "enclawed.boot",
#   "payload": {
#     "pid": 12345,
#     "flavor": "open",
#     "enforceAllowlists": true,
#     "allowedChannels": [],
#     "allowedProviders": [],
#     "allowedHosts":     ["127.0.0.1", "::1", "localhost"],
#     "fipsRequired": false
#   } }

Every bootstrapEnclawed() call appends one enclawed.boot record with the resolved policy. The audit chain proves these values match what the process is enforcing.

5Run a research query

The research-agent system prompt encodes the citation rules; configure it once with enclawed configure or enclawed agents add --agent research:

You are a research agent grounded on the local memory store.

Rules:
  1. Every claim in your answer MUST be supported by a chunk you
     retrieved via memory_recall. If no chunk supports a claim,
     say "I do not have a citation for this" and stop.
  2. Cite as [file basename, page N] inline.
  3. If memory_recall returns nothing relevant, answer:
     "no relevant material in the corpus."
  4. Never produce a URL. The corpus is local-only.

Then ask one question per turn:

enclawed agent \
  --agent research \
  --local \
  --message "What does the 2024 report say about expected revenue growth in Q4?"

For repeatable runs you can also use enclawed run ./ask.md --var question="..." with a markdown task file (## System / ## User sections) — the runner substitutes {{question}} and dispatches through the same agent path.

6Verify no traffic left the host

The audit log records every network attempt the agent made — both the allowed loopback calls to your local model and any blocked outbound attempts. If you want to be extra sure, run a packet sniffer at the same time:

# From a second terminal, before the query:
sudo tcpdump -i any -n 'not (host 127.0.0.1 or host ::1)' \
  and 'port 80 or port 443'

# Run the query in the first terminal, then:
#   tcpdump should report:
#     0 packets captured
#     0 packets received by filter

# Verify the audit chain.
enclawed audit verify

# Search for any egress denials in the default log:
grep '"type":"egress.deny"' ~/.enclawed/audit.jsonl | wc -l
# (should be 0 in a clean run; non-zero means something tried
#  to reach an external host and was blocked - investigate.)