minirag-pgvector-mcp: Skill for Claude Code

Distribute raw documents into the vector store: parse → chunk → embed → upsert. The evolution of your manual "ingest skill" that moved raw meeting minutes into the right folder — now it also chunks and embeds.

When to invoke

• New raw documents need to go into the vector store.
• You want to (re-)ingest your existing context/ repo.
• A source changed and needs re-embedding.

Inputs

• path — file or directory.
• doctype (optional) — one of the known types. If omitted, infer from the containing folder name (mirrors your folder-as-category convention).

Procedure

1. Read-only survey first. List the files to be ingested and the doctype each will get. Print the plan. Do not write yet.
2. Confirm the doctype mapping looks right (especially for inferred ones).
3. For each file:
   • Parse text; for markdown, capture heading_path per section.
   • Chunk using the strategy for its doctype (see docs/architecture.md).
   • Embed chunks with the active embedder.
   • Compute source_hash. If the document exists with the same hash → skip (idempotent). If it exists with a different hash → replace its chunks.
   • Upsert documents + chunks with metadata (doctype, source, heading_path, embedder_id, ingested_at).
4. Report: per file — chunks created / skipped / replaced. Aggregate by doctype.

Guardrails

• Never embed with a model whose dimension ≠ the pgvector column dimension. Assert first.
• Never duplicate a source. Idempotency is keyed on source_hash.
• Do not invent doctypes silently. If a folder name doesn't map to a known doctype, surface it and ask rather than defaulting.
• Large batches: embed in batches; don't hold everything in memory.

Verification

After ingest, run:

SELECT doctype, count(*) FROM chunks GROUP BY doctype;

Counts should match the plan printed in step 1. Re-running the same ingest must not change counts.

Failure modes to watch (self-check)

• Chunking mid-code-block or mid-table (breaks meaning) → check the doctype strategy.
• Silent embedder swap (dimension mismatch or mixed embedder_id) → refuse and report.
• Over-trusting that "it ran" = "it's correct" → always print the verification query, don't assume.