mcp-scraper 0.24.0 → 0.25.0

package/dist/chunk-UELJZCUC.js

@@ -0,0 +1,7 @@
+// src/version.ts
+var PACKAGE_VERSION = "0.25.0";
+
+export {
+  PACKAGE_VERSION
+};
+//# sourceMappingURL=chunk-UELJZCUC.js.map

package/dist/chunk-UELJZCUC.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/version.ts"],"sourcesContent":["export const PACKAGE_VERSION = '0.25.0'\n"],"mappings":";AAAO,IAAM,kBAAkB;","names":[]}

package/dist/{server-I5U3OUZZ.js → server-PILR3U5E.js}

@@ -35,7 +35,7 @@ import {
   sanitizeAttempts,
   sanitizeHarvestResult,
   transcribeMediaUrl
-} from "./chunk-SUPUHPJS.js";
+} from "./chunk-NC37L5RW.js";
 import {
   auditImages,
   buildLinkReport,
@@ -76,7 +76,7 @@ import {
   RawMapsOverviewSchema,
   RawMapsReviewStatsSchema
 } from "./chunk-XGIPATLV.js";
-import "./chunk-CDLHUCMT.js";
+import "./chunk-UELJZCUC.js";
 import {
   completeExtractJob,
   countSuccessfulPages,
@@ -25191,4 +25191,4 @@ app.get("/blog/:slug/", (c) => {
 export {
   app
 };
-//# sourceMappingURL=server-I5U3OUZZ.js.map
+//# sourceMappingURL=server-PILR3U5E.js.map

package/docs/adr/0002-hybrid-smart-rag-vault-retrieval.md

@@ -0,0 +1,62 @@
+# ADR 0002: Hybrid Smart RAG retrieval for memory vaults
+
+- **Status:** Accepted
+- **Date:** 2026-07-16
+- **Deciders:** Andrew (operator), engineering
+- **Applies to:** MCP Memory retrieval, memory writes, vault search, and the default Skills vault
+
+## Context
+
+Semantic similarity alone can miss exact tags, dates, metadata, and the note graph that gives an Obsidian vault its useful local context. Expanding every link from every semantic result has the opposite problem: it creates a large, noisy candidate set and can make structural proximity look like evidence of relevance. The connected AI also needs a strong habit of reusing the live tag vocabulary without turning one advisory tool-call order into a persisted write precondition.
+
+Skills add a second vault-specific constraint. A stored skill is not just one note: its internal links may point to reference material, templates, and executable support files, so the vault needs a stable folder contract.
+
+## Decision
+
+**Use bounded hybrid Smart RAG for memory retrieval, and treat tag and graph context as evidence-bearing candidates rather than automatic conclusions.**
+
+The default retrieval flow is:
+
+1. Form **2–4 focused query variants**, with **3** as the default.
+2. Combine exact **tag, metadata, vault, and date** retrieval with semantic retrieval.
+3. Fuse and deduplicate those channels into a total candidate pool of **50**.
+4. Select the top **8** preliminary seeds.
+5. Expand each seed to **depth 1**, considering at most **5** outgoing links or backlinks per seed.
+6. Apply **Jina reranking** to the combined candidates and retain the top **30** for reasoning.
+
+Graph-expanded items remain candidates. They are not automatically relevant and must never become automatic note links; the AI adds an internal link only when the note contents support it.
+
+Before memory search, creation, or update, the MCP instructions strongly direct the AI to inspect the complete accessible tag inventory, reuse existing tags, and add a tag only when the inventory does not contain an adequate equivalent. This is an automatic behavioral directive, **not** a persisted call-order precondition that makes writes fail solely because a separate tag-list call was not recorded.
+
+The default **Skills** vault stores reusable skill packages. Every skill requires a `scripts/` folder and at least one of `references/` or `templates/`; a skill may have both. Skill notes use normal internal links to those supporting files.
+
+## Consequences
+
+**Positive**
+- Exact filters preserve high-precision matches while multi-query semantic retrieval recovers differently worded concepts.
+- Bounded one-hop expansion recovers directly connected context without recursively walking the vault.
+- Jina reranking makes semantic, exact, and graph-derived candidates comparable before the AI reasons over them.
+- The 50-candidate and 30-result bounds provide predictable retrieval and context costs.
+- Tag reuse becomes the default AI behavior without coupling persisted data validity to orchestration traces.
+- Skills have a portable, inspectable support-file layout.
+
+**Negative / risks**
+- Multi-query retrieval, graph expansion, and reranking add latency and Jina dependency cost.
+- A fixed pool of 50 may under-recall unusually broad vaults; 30 reranked notes may still exceed the useful reading budget for narrow questions.
+- Link quality depends on note contents and graph maintenance; a bad link can introduce a weak candidate even though reranking limits its impact.
+- The tag-inventory-first behavior remains advisory at the AI layer and can be skipped by a non-compliant client.
+- Skills that do not need executable logic must still carry a `scripts/` folder to satisfy the vault contract.
+
+## Alternatives considered
+
+- **One semantic query only.** Rejected because it misses exact structured constraints and alternate phrasings.
+- **Expand every link from every retrieved note.** Rejected because candidate growth and graph noise become unbounded; expansion is limited to the strongest eight seeds.
+- **Treat graph neighbors as automatically relevant or automatically link them.** Rejected because structural proximity is not evidence that a note answers the current request.
+- **Persist tag-list call order as a write precondition.** Rejected because it couples durable writes to client orchestration history; forceful instructions provide the intended behavior without rejecting otherwise valid writes.
+
+## Revisit when
+
+- Retrieval evaluation shows that the 50/8/5/30 bounds materially harm recall or precision.
+- Jina reranking becomes unavailable, too costly, or is outperformed by a tested replacement.
+- Vault graphs become dense enough that one-hop expansion regularly adds mostly irrelevant candidates.
+- The Skills packaging contract adopts an external standard that makes `scripts/`, `references/`, or `templates/` incompatible.

package/docs/adr/README.md

@@ -9,3 +9,4 @@ Write one when a decision is hard to reverse, surprising, or encodes a constrain
 
 ## Index
 - [0001 — In-page API interception for anti-bot scraping (Facebook Ad Library)](./0001-in-page-graphql-interception-for-anti-bot-scraping.md)
+- [0002 — Hybrid Smart RAG retrieval for memory vaults](./0002-hybrid-smart-rag-vault-retrieval.md)