Skip to content

A self-hostable bookmark-everything app (links, notes and images) with AI-based automatic tagging and full text search

feat: add semantic search (#2959)

Mohamed Bassem71ea4d9b42d3
diff --git a/apps/cli/src/commands/bookmarks.ts b/apps/cli/src/commands/bookmarks.ts
index 17f1dd5d..d2f9e254 100644
--- a/apps/cli/src/commands/bookmarks.ts
+++ b/apps/cli/src/commands/bookmarks.ts
@@ -615,6 +615,17 @@ bookmarkCmd
},
"relevance",
)
+ .option(
+ "--search-mode <mode>",
+ "search mode (fts, semantic, or hybrid)",
+ (val) => {
+ if (val !== "fts" && val !== "semantic" && val !== "hybrid") {
+ throw new Error("search-mode must be one of: fts, semantic, hybrid");
+ }
+ return val;
+ },
+ "fts",
+ )
.option(
"--include-content",
"include full bookmark content in results",
@@ -629,6 +640,7 @@ bookmarkCmd
text: query,
limit: opts.limit,
sortOrder: opts.sortOrder as "relevance" | "asc" | "desc",
+ searchMode: opts.searchMode as "fts" | "semantic" | "hybrid",
includeContent: opts.includeContent,
cursor: opts.cursor
? JSON.parse(Buffer.from(opts.cursor, "base64").toString(), (k, v) =>
diff --git a/apps/mcp/src/bookmarks.test.ts b/apps/mcp/src/bookmarks.test.ts
index dc3e45c7..e72aefc8 100644
--- a/apps/mcp/src/bookmarks.test.ts
+++ b/apps/mcp/src/bookmarks.test.ts
@@ -23,6 +23,7 @@ import {
deleteBookmarkHandler,
getBookmarkContentHandler,
getBookmarkListsHandler,
+ searchBookmarksHandler,
} from "./bookmarks";
const textOf = (result: CallToolResult): string => {
@@ -80,6 +81,35 @@ afterEach(() => {
vi.clearAllMocks();
});
+describe("search-bookmarks", () => {
+ it("forwards the selected search mode", async () => {
+ mockClient.GET.mockResolvedValueOnce({
+ data: { bookmarks: [sampleBookmark], nextCursor: null },
+ error: undefined,
+ });
+
+ const result = await searchBookmarksHandler({
+ query: "async concurrency",
+ limit: 10,
+ searchMode: "semantic",
+ });
+
+ expect(mockClient.GET).toHaveBeenCalledWith("/bookmarks/search", {
+ params: {
+ query: {
+ q: "async concurrency",
+ limit: 10,
+ includeContent: false,
+ cursor: undefined,
+ sortOrder: undefined,
+ searchMode: "semantic",
+ },
+ },
+ });
+ expect(textOf(result)).toContain("Rust async book");
+ });
+});
+
describe("get-bookmark-lists", () => {
it("returns every list containing the bookmark", async () => {
mockClient.GET.mockResolvedValueOnce({
diff --git a/apps/mcp/src/bookmarks.ts b/apps/mcp/src/bookmarks.ts
index 51f94489..d464aecf 100644
--- a/apps/mcp/src/bookmarks.ts
+++ b/apps/mcp/src/bookmarks.ts
@@ -5,12 +5,8 @@ import { karakeepClient, mcpServer, turndownService } from "./shared";
import { compactBookmark, compactList, toMcpToolError } from "./utils";
// Tools
-mcpServer.tool(
- "search-bookmarks",
- `Search for bookmarks matching a specific a query.
-`,
- {
- query: z.string().describe(`
+export const searchBookmarksInputSchema = {
+ query: z.string().describe(`
By default, this will do a full-text search, but you can also use qualifiers to filter the results.
You can search bookmarks using specific qualifiers. is:fav finds favorited bookmarks,
is:archived searches archived bookmarks, is:tagged finds those with tags,
@@ -29,50 +25,75 @@ is:archived and (list:reading or #work)
### Combine text search with qualifiers
machine learning is:fav`),
- limit: z
- .number()
- .optional()
- .describe(`The number of results to return in a single query.`)
- .default(10),
- nextCursor: z
- .string()
- .optional()
- .describe(
- `The next cursor to use for pagination. The value for this is returned from a previous call to this tool.`,
- ),
- sortOrder: z
- .enum(["asc", "desc", "relevance"])
- .optional()
- .describe(`Sort by relevance or creation date. Defaults to relevance.`),
- },
- async ({ query, limit, nextCursor, sortOrder }): Promise<CallToolResult> => {
- const res = await karakeepClient.GET("/bookmarks/search", {
- params: {
- query: {
- q: query,
- limit: limit,
- includeContent: false,
- cursor: nextCursor,
- sortOrder,
- },
+ limit: z
+ .number()
+ .optional()
+ .describe(`The number of results to return in a single query.`)
+ .default(10),
+ nextCursor: z
+ .string()
+ .optional()
+ .describe(
+ `The next cursor to use for pagination. The value for this is returned from a previous call to this tool.`,
+ ),
+ sortOrder: z
+ .enum(["asc", "desc", "relevance"])
+ .optional()
+ .describe(`Sort by relevance or creation date. Defaults to relevance.`),
+ searchMode: z
+ .enum(["fts", "semantic", "hybrid"])
+ .optional()
+ .describe(
+ `Search strategy. 'fts' uses full-text search, 'semantic' uses embeddings, and 'hybrid' combines both. Semantic and hybrid modes only support relevance sorting. Defaults to 'fts'.`,
+ )
+ .default("fts"),
+};
+
+export type SearchBookmarksInput = z.infer<
+ z.ZodObject<typeof searchBookmarksInputSchema>
+>;
+
+export async function searchBookmarksHandler({
+ query,
+ limit,
+ nextCursor,
+ sortOrder,
+ searchMode,
+}: SearchBookmarksInput): Promise<CallToolResult> {
+ const res = await karakeepClient.GET("/bookmarks/search", {
+ params: {
+ query: {
+ q: query,
+ limit: limit,
+ includeContent: false,
+ cursor: nextCursor,
+ sortOrder,
+ searchMode,
},
- });
- if (!res.data) {
- return toMcpToolError(res.error);
- }
- return {
- content: [
- {
- type: "text",
- text: `
+ },
+ });
+ if (!res.data) {
+ return toMcpToolError(res.error);
+ }
+ return {
+ content: [
+ {
+ type: "text",
+ text: `
${res.data.bookmarks.map((bm) => compactBookmark(bm)).join("\n\n")}
Next cursor: ${res.data.nextCursor ? `'${res.data.nextCursor}'` : "no more pages"}
`,
- },
- ],
- };
- },
+ },
+ ],
+ };
+}
+
+mcpServer.tool(
+ "search-bookmarks",
+ `Search for bookmarks matching a specific query using full-text, semantic, or hybrid search.`,
+ searchBookmarksInputSchema,
+ searchBookmarksHandler,
);
mcpServer.tool(
diff --git a/packages/api/routes/bookmarks.ts b/packages/api/routes/bookmarks.ts
index 990b0a74..19897113 100644
--- a/packages/api/routes/bookmarks.ts
+++ b/packages/api/routes/bookmarks.ts
@@ -85,6 +85,8 @@ const app = new Hono()
text: searchParams.q,
cursor: searchParams.cursor,
limit: searchParams.limit,
+ sortOrder: searchParams.sortOrder,
+ searchMode: searchParams.searchMode,
includeContent: searchParams.includeContent,
});
return c.json(
diff --git a/packages/api/utils/types.ts b/packages/api/utils/types.ts
index 6fe9b880..34b9b3b0 100644
--- a/packages/api/utils/types.ts
+++ b/packages/api/utils/types.ts
@@ -1,6 +1,9 @@
import { z } from "zod";
-import { zSortOrder } from "@karakeep/shared/types/bookmarks";
+import {
+ zBookmarkSearchMode,
+ zSortOrder,
+} from "@karakeep/shared/types/bookmarks";
export const zStringBool = z
.string()
@@ -23,5 +26,6 @@ export const zGetBookmarkQueryParamsSchema = z
export const zGetBookmarkSearchParamsSchema = z
.object({
sortOrder: zSortOrder.optional().default(zSortOrder.enum.relevance),
+ searchMode: zBookmarkSearchMode.optional().default("fts"),
})
.extend(zIncludeContentSearchParamsSchema.shape);
diff --git a/packages/open-api/karakeep-openapi-spec.json b/packages/open-api/karakeep-openapi-spec.json
index 387a50e0..1a118f4d 100644
--- a/packages/open-api/karakeep-openapi-spec.json
+++ b/packages/open-api/karakeep-openapi-spec.json
@@ -1188,7 +1188,7 @@
"/bookmarks/search": {
"get": {
"operationId": "searchBookmarks",
- "description": "Full-text search across all bookmarks. Searches bookmark titles, content, descriptions, and notes. Results default to relevance sorting.",
+ "description": "Search across all bookmarks using full-text, semantic, or hybrid ranking. Full-text search covers bookmark titles, content, descriptions, and notes. Results default to full-text relevance sorting; semantic and hybrid modes support relevance sorting only.",
"summary": "Search bookmarks",
"tags": [
"Bookmarks"
@@ -1209,6 +1209,22 @@
"name": "q",
"in": "query"
},
+ {
+ "schema": {
+ "type": "string",
+ "enum": [
+ "fts",
+ "semantic",
+ "hybrid"
+ ],
+ "default": "fts",
+ "description": "Search strategy. 'fts' uses full-text search, 'semantic' uses bookmark embeddings, and 'hybrid' fuses a fixed candidate window from both. Hybrid falls back to full-text search when the query contains no free-text terms or when embedding infrastructure is unavailable. Semantic hits below a minimum similarity are dropped, so semantic search may return fewer results than requested."
+ },
+ "required": false,
+ "description": "Search strategy. 'fts' uses full-text search, 'semantic' uses bookmark embeddings, and 'hybrid' fuses a fixed candidate window from both. Hybrid falls back to full-text search when the query contains no free-text terms or when embedding infrastructure is unavailable. Semantic hits below a minimum similarity are dropped, so semantic search may return fewer results than requested.",
+ "name": "searchMode",
+ "in": "query"
+ },
{
"schema": {
"type": "string",
diff --git a/packages/open-api/lib/bookmarks.ts b/packages/open-api/lib/bookmarks.ts
index ce65a84e..2dfd6520 100644
--- a/packages/open-api/lib/bookmarks.ts
+++ b/packages/open-api/lib/bookmarks.ts
@@ -9,6 +9,7 @@ import {
zAssetTypesSchema,
zBareBookmarkSchema,
zBookmarkReadableContentFormatSchema,
+ zBookmarkSearchMode,
zManipulatedTagSchema,
zNewBookmarkRequestSchema,
zSortOrder,
@@ -86,8 +87,8 @@ registry.registerPath({
method: "get",
path: "/bookmarks/search",
description:
- "Full-text search across all bookmarks. Searches bookmark titles, content, descriptions, and notes. " +
- "Results default to relevance sorting.",
+ "Search across all bookmarks using full-text, semantic, or hybrid ranking. Full-text search covers bookmark titles, content, descriptions, and notes. " +
+ "Results default to full-text relevance sorting; semantic and hybrid modes support relevance sorting only.",
summary: "Search bookmarks",
tags: ["Bookmarks"],
security: [{ [BearerAuth.name]: [] }],
@@ -95,6 +96,12 @@ registry.registerPath({
query: z
.object({
q: z.string().describe("The search query string."),
+ searchMode: zBookmarkSearchMode
+ .optional()
+ .default("fts")
+ .describe(
+ "Search strategy. 'fts' uses full-text search, 'semantic' uses bookmark embeddings, and 'hybrid' fuses a fixed candidate window from both. Hybrid falls back to full-text search when the query contains no free-text terms or when embedding infrastructure is unavailable. Semantic hits below a minimum similarity are dropped, so semantic search may return fewer results than requested.",
+ ),
sortOrder: zSortOrder
.optional()
.default(zSortOrder.enum.relevance)
diff --git a/packages/sdk/src/karakeep-api.d.ts b/packages/sdk/src/karakeep-api.d.ts
index 6883c59e..89564cf2 100644
--- a/packages/sdk/src/karakeep-api.d.ts
+++ b/packages/sdk/src/karakeep-api.d.ts
@@ -37,7 +37,7 @@ export interface paths {
};
/**
* Search bookmarks
- * @description Full-text search across all bookmarks. Searches bookmark titles, content, descriptions, and notes. Results default to relevance sorting.
+ * @description Search across all bookmarks using full-text, semantic, or hybrid ranking. Full-text search covers bookmark titles, content, descriptions, and notes. Results default to full-text relevance sorting; semantic and hybrid modes support relevance sorting only.
*/
get: operations["searchBookmarks"];
put?: never;
@@ -1219,6 +1219,8 @@ export interface operations {
query: {
/** @description The search query string. */
q: string;
+ /** @description Search strategy. 'fts' uses full-text search, 'semantic' uses bookmark embeddings, and 'hybrid' fuses a fixed candidate window from both. Hybrid falls back to full-text search when the query contains no free-text terms or when embedding infrastructure is unavailable. Semantic hits below a minimum similarity are dropped, so semantic search may return fewer results than requested. */
+ searchMode?: "fts" | "semantic" | "hybrid";
/** @description Sort order for results. Defaults to 'relevance'. Use 'asc' or 'desc' for date-based sorting. */
sortOrder?: "asc" | "desc" | "relevance";
/** @description Maximum number of items to return per page. */
diff --git a/packages/shared-server/src/eventLogTypes.ts b/packages/shared-server/src/eventLogTypes.ts
index 21a15f5e..e8623159 100644
--- a/packages/shared-server/src/eventLogTypes.ts
+++ b/packages/shared-server/src/eventLogTypes.ts
@@ -172,6 +172,8 @@ type EventLogInternal =
| {
["event.name"]: "search.query";
"search.has_query"?: boolean;
+ "search.mode"?: "fts" | "semantic" | "hybrid";
+ "search.degraded"?: boolean;
"search.results_count"?: number;
}
| { ["event.name"]: "bookmarks.queried" }
diff --git a/packages/shared/types/bookmarks.ts b/packages/shared/types/bookmarks.ts
index b9ce5277..8626a9c4 100644
--- a/packages/shared/types/bookmarks.ts
+++ b/packages/shared/types/bookmarks.ts
@@ -307,11 +307,13 @@ export const zSearchBookmarksCursor = z.discriminatedUnion("ver", [
offset: z.number(),
}),
]);
+export const zBookmarkSearchMode = z.enum(["fts", "semantic", "hybrid"]);
export const zSearchBookmarksRequestSchema = z.object({
text: z.string(),
limit: z.number().max(MAX_NUM_BOOKMARKS_PER_PAGE).optional(),
cursor: zSearchBookmarksCursor.nullish(),
sortOrder: zSortOrder.optional().default("relevance"),
+ searchMode: zBookmarkSearchMode.optional().default("fts"),
includeContent: z.boolean().optional().default(false),
});
diff --git a/packages/trpc/lib/__tests__/searchRanking.test.ts b/packages/trpc/lib/__tests__/searchRanking.test.ts
new file mode 100644
index 00000000..0ad48048
--- /dev/null
+++ b/packages/trpc/lib/__tests__/searchRanking.test.ts
@@ -0,0 +1,43 @@
+import { describe, expect, test } from "vitest";
+
+import { reciprocalRankFusion } from "../searchRanking";
+
+describe("reciprocalRankFusion", () => {
+ test("rewards results returned by both search engines", () => {
+ const results = reciprocalRankFusion([
+ [{ id: "fts-only" }, { id: "both" }],
+ [{ id: "semantic-only" }, { id: "both" }],
+ ]);
+
+ expect(results.map((result) => result.id)).toEqual([
+ "both",
+ "fts-only",
+ "semantic-only",
+ ]);
+ });
+
+ test("keeps source order when only one list contains a result", () => {
+ const results = reciprocalRankFusion([
+ [{ id: "first" }, { id: "second" }, { id: "third" }],
+ [],
+ ]);
+
+ expect(results.map((result) => result.id)).toEqual([
+ "first",
+ "second",
+ "third",
+ ]);
+ });
+
+ test("counts duplicate ids only once per source", () => {
+ const results = reciprocalRankFusion(
+ [[{ id: "duplicate" }, { id: "duplicate" }], [{ id: "other" }]],
+ 0,
+ );
+
+ expect(results).toEqual([
+ { id: "duplicate", score: 1 },
+ { id: "other", score: 1 },
+ ]);
+ });
+});
diff --git a/packages/trpc/lib/searchRanking.ts b/packages/trpc/lib/searchRanking.ts
new file mode 100644
index 00000000..e75f53fd
--- /dev/null
+++ b/packages/trpc/lib/searchRanking.ts
@@ -0,0 +1,47 @@
+export interface RankedSearchHit {
+ id: string;
+ score: number;
+}
+
+/**
+ * Merge ranked result lists using reciprocal-rank fusion (RRF).
+ *
+ * RRF deliberately ignores source scores because full-text and vector search
+ * scores do not share a meaningful scale. A hit receives credit for its rank
+ * in every source, so results returned by both sources naturally rise.
+ */
+export function reciprocalRankFusion(
+ resultLists: readonly (readonly { id: string }[])[],
+ rankConstant = 60,
+): RankedSearchHit[] {
+ const scores = new Map<string, { score: number; bestRank: number }>();
+
+ for (const hits of resultLists) {
+ const seen = new Set<string>();
+ hits.forEach((hit, index) => {
+ if (seen.has(hit.id)) {
+ return;
+ }
+ seen.add(hit.id);
+
+ const rank = index + 1;
+ const current = scores.get(hit.id) ?? {
+ score: 0,
+ bestRank: Number.POSITIVE_INFINITY,
+ };
+ current.score += 1 / (rankConstant + rank);
+ current.bestRank = Math.min(current.bestRank, rank);
+ scores.set(hit.id, current);
+ });
+ }
+
+ return [...scores.entries()]
+ .map(([id, ranking]) => ({ id, ...ranking }))
+ .sort(
+ (a, b) =>
+ b.score - a.score ||
+ a.bestRank - b.bestRank ||
+ a.id.localeCompare(b.id),
+ )
+ .map(({ id, score }) => ({ id, score }));
+}
diff --git a/packages/trpc/routers/bookmarks.search.test.ts b/packages/trpc/routers/bookmarks.search.test.ts
new file mode 100644
index 00000000..26e7bc37
--- /dev/null
+++ b/packages/trpc/routers/bookmarks.search.test.ts
@@ -0,0 +1,433 @@
+import { beforeEach, describe, expect, test, vi } from "vitest";
+
+import serverConfig from "@karakeep/shared/config";
+import { BookmarkTypes } from "@karakeep/shared/types/bookmarks";
+
+import type { CustomTestContext } from "../testUtils";
+import { defaultBeforeEach } from "../testUtils";
+import { createSemanticSearchRateLimitMiddleware } from "./bookmarks";
+
+const searchMocks = vi.hoisted(() => ({
+ search: vi.fn(),
+ vectorSearch: vi.fn(),
+ buildInferenceClient: vi.fn(),
+ getVectorStoreClient: vi.fn(),
+ getRateLimitClient: vi.fn(),
+ checkRateLimit: vi.fn(),
+}));
+
+vi.mock("@karakeep/shared/inference", () => ({
+ InferenceClientFactory: {
+ build: searchMocks.buildInferenceClient,
+ },
+}));
+
+vi.mock("@karakeep/shared/search", async (original) => ({
+ ...(await original<typeof import("@karakeep/shared/search")>()),
+ getSearchClient: vi.fn(async () => ({ search: searchMocks.search })),
+}));
+
+vi.mock("@karakeep/shared/vectorStore", async (original) => ({
+ ...(await original<typeof import("@karakeep/shared/vectorStore")>()),
+ getVectorStoreClient: searchMocks.getVectorStoreClient,
+}));
+
+vi.mock("@karakeep/shared/ratelimiting", async (original) => ({
+ ...(await original<typeof import("@karakeep/shared/ratelimiting")>()),
+ getRateLimitClient: searchMocks.getRateLimitClient,
+}));
+
+beforeEach<CustomTestContext>(async (context) => {
+ await defaultBeforeEach(true)(context);
+ searchMocks.search.mockReset();
+ searchMocks.vectorSearch.mockReset();
+ searchMocks.buildInferenceClient.mockReset();
+ searchMocks.getVectorStoreClient.mockReset();
+ searchMocks.getRateLimitClient.mockReset();
+ searchMocks.checkRateLimit.mockReset();
+ searchMocks.getVectorStoreClient.mockResolvedValue({
+ search: searchMocks.vectorSearch,
+ });
+ searchMocks.getRateLimitClient.mockResolvedValue(null);
+});
+
+function mockEmbeddingInfra() {
+ const generateEmbeddingFromText = vi.fn(async () => ({
+ embeddings: [[0.1, 0.2]],
+ promptTokens: 1,
+ totalTokens: 1,
+ }));
+ searchMocks.buildInferenceClient.mockReturnValue({
+ generateEmbeddingFromText,
+ });
+ return generateEmbeddingFromText;
+}
+
+describe("bookmark search modes", () => {
+ test.each(["semantic", "hybrid"] as const)(
+ "rate limits %s search",
+ async (searchMode) => {
+ const next = vi.fn().mockResolvedValue("ok");
+ searchMocks.checkRateLimit.mockResolvedValue({ allowed: true });
+ searchMocks.getRateLimitClient.mockResolvedValue({
+ checkRateLimit: searchMocks.checkRateLimit,
+ });
+ const wasRateLimitingEnabled = serverConfig.rateLimiting.enabled;
+ serverConfig.rateLimiting.enabled = true;
+
+ try {
+ const result = await createSemanticSearchRateLimitMiddleware<string>()({
+ path: "bookmarks.searchBookmarks",
+ ctx: {
+ req: { ip: "127.0.0.1" },
+ user: { id: "user-123" },
+ },
+ input: { searchMode },
+ next,
+ });
+
+ expect(result).toBe("ok");
+ expect(searchMocks.checkRateLimit).toHaveBeenCalledWith(
+ {
+ name: "bookmarks.searchBookmarks.semantic",
+ windowMs: 60_000,
+ maxRequests: 300,
+ },
+ "127.0.0.1:user:user-123:bookmarks.searchBookmarks",
+ );
+ } finally {
+ serverConfig.rateLimiting.enabled = wasRateLimitingEnabled;
+ }
+ },
+ );
+
+ test("does not apply the semantic search rate limit to full-text search", async () => {
+ const next = vi.fn().mockResolvedValue("ok");
+ const wasRateLimitingEnabled = serverConfig.rateLimiting.enabled;
+ serverConfig.rateLimiting.enabled = true;
+
+ try {
+ const result = await createSemanticSearchRateLimitMiddleware<string>()({
+ path: "bookmarks.searchBookmarks",
+ ctx: {
+ req: { ip: "127.0.0.1" },
+ user: { id: "user-123" },
+ },
+ input: { searchMode: "fts" },
+ next,
+ });
+
+ expect(result).toBe("ok");
+ expect(searchMocks.getRateLimitClient).not.toHaveBeenCalled();
+ } finally {
+ serverConfig.rateLimiting.enabled = wasRateLimitingEnabled;
+ }
+ });
+
+ test<CustomTestContext>("defaults to full-text search", async ({
+ apiCallers,
+ }) => {
+ const bookmark = await apiCallers[0].bookmarks.createBookmark({
+ type: BookmarkTypes.TEXT,
+ text: "full text result",
+ });
+ searchMocks.search.mockResolvedValue({
+ hits: [{ id: bookmark.id, score: 1 }],
+ totalHits: 1,
+ processingTimeMs: 1,
+ });
+
+ const result = await apiCallers[0].bookmarks.searchBookmarks({
+ text: "result",
+ });
+
+ expect(result.bookmarks.map((item) => item.id)).toEqual([bookmark.id]);
+ expect(searchMocks.vectorSearch).not.toHaveBeenCalled();
+ });
+
+ test<CustomTestContext>("fuses full-text and semantic rankings", async ({
+ apiCallers,
+ }) => {
+ const [ftsOnly, shared, semanticOnly] = await Promise.all(
+ ["full text", "shared", "semantic"].map((text) =>
+ apiCallers[0].bookmarks.createBookmark({
+ type: BookmarkTypes.TEXT,
+ text,
+ }),
+ ),
+ );
+ searchMocks.search.mockResolvedValue({
+ hits: [
+ { id: ftsOnly.id, score: 1 },
+ { id: shared.id, score: 0.5 },
+ ],
+ totalHits: 2,
+ processingTimeMs: 1,
+ });
+ searchMocks.vectorSearch.mockResolvedValue({
+ hits: [
+ { id: semanticOnly.id, score: 0.95 },
+ { id: shared.id, score: 0.9 },
+ ],
+ processingTimeMs: 1,
+ });
+ const generateEmbeddingFromText = mockEmbeddingInfra();
+
+ const result = await apiCallers[0].bookmarks.searchBookmarks({
+ text: "meaningful query",
+ searchMode: "hybrid",
+ });
+
+ expect(result.bookmarks[0]?.id).toBe(shared.id);
+ expect(new Set(result.bookmarks.slice(1).map((item) => item.id))).toEqual(
+ new Set([ftsOnly.id, semanticOnly.id]),
+ );
+ expect(generateEmbeddingFromText).toHaveBeenCalledWith([
+ "meaningful query",
+ ]);
+ expect(searchMocks.vectorSearch).toHaveBeenCalledWith(
+ expect.objectContaining({
+ vector: [0.1, 0.2],
+ limit: 100,
+ filter: [
+ {
+ type: "eq",
+ field: "userId",
+ value: expect.any(String),
+ },
+ ],
+ }),
+ );
+ expect(searchMocks.search).toHaveBeenCalledWith(
+ expect.objectContaining({ limit: 100 }),
+ );
+ });
+
+ test<CustomTestContext>("falls back to full-text search when hybrid infrastructure is unavailable", async ({
+ apiCallers,
+ }) => {
+ const bookmark = await apiCallers[0].bookmarks.createBookmark({
+ type: BookmarkTypes.TEXT,
+ text: "fallback result",
+ });
+ searchMocks.buildInferenceClient.mockReturnValue(null);
+ searchMocks.getVectorStoreClient.mockResolvedValue(null);
+ searchMocks.search.mockResolvedValue({
+ hits: [{ id: bookmark.id, score: 1 }],
+ totalHits: 1,
+ processingTimeMs: 1,
+ });
+
+ const result = await apiCallers[0].bookmarks.searchBookmarks({
+ text: "fallback",
+ searchMode: "hybrid",
+ });
+
+ expect(result.bookmarks.map((item) => item.id)).toEqual([bookmark.id]);
+ expect(searchMocks.vectorSearch).not.toHaveBeenCalled();
+ expect(searchMocks.search).toHaveBeenCalledWith(
+ expect.objectContaining({ limit: 20, offset: 0 }),
+ );
+ });
+
+ test<CustomTestContext>("falls back when the hybrid vector store fails to initialize", async ({
+ apiCallers,
+ }) => {
+ const bookmark = await apiCallers[0].bookmarks.createBookmark({
+ type: BookmarkTypes.TEXT,
+ text: "vector initialization fallback",
+ });
+ mockEmbeddingInfra();
+ searchMocks.getVectorStoreClient.mockRejectedValue(
+ new Error("vector store unavailable"),
+ );
+ searchMocks.search.mockResolvedValue({
+ hits: [{ id: bookmark.id, score: 1 }],
+ totalHits: 1,
+ processingTimeMs: 1,
+ });
+
+ const result = await apiCallers[0].bookmarks.searchBookmarks({
+ text: "fallback",
+ searchMode: "hybrid",
+ });
+
+ expect(result.bookmarks.map((item) => item.id)).toEqual([bookmark.id]);
+ expect(searchMocks.search).toHaveBeenCalledWith(
+ expect.objectContaining({ limit: 20, offset: 0 }),
+ );
+ });
+
+ test<CustomTestContext>("falls back to a correctly paginated full-text page when hybrid vector search fails", async ({
+ apiCallers,
+ }) => {
+ const bookmark = await apiCallers[0].bookmarks.createBookmark({
+ type: BookmarkTypes.TEXT,
+ text: "runtime fallback",
+ });
+ mockEmbeddingInfra();
+ searchMocks.vectorSearch.mockRejectedValue(
+ new Error("vector query unavailable"),
+ );
+ searchMocks.search.mockResolvedValue({
+ hits: [{ id: bookmark.id, score: 1 }],
+ totalHits: 41,
+ processingTimeMs: 1,
+ });
+
+ const result = await apiCallers[0].bookmarks.searchBookmarks({
+ text: "fallback",
+ searchMode: "hybrid",
+ limit: 10,
+ cursor: { ver: 1, offset: 40 },
+ });
+
+ expect(result.bookmarks.map((item) => item.id)).toEqual([bookmark.id]);
+ expect(searchMocks.search).toHaveBeenNthCalledWith(
+ 1,
+ expect.objectContaining({ limit: 100 }),
+ );
+ expect(searchMocks.search).toHaveBeenNthCalledWith(
+ 2,
+ expect.objectContaining({ limit: 10, offset: 40 }),
+ );
+ });
+
+ test<CustomTestContext>("falls back when hybrid embedding generation fails", async ({
+ apiCallers,
+ }) => {
+ const bookmark = await apiCallers[0].bookmarks.createBookmark({
+ type: BookmarkTypes.TEXT,
+ text: "embedding fallback",
+ });
+ const generateEmbeddingFromText = mockEmbeddingInfra();
+ generateEmbeddingFromText.mockRejectedValue(
+ new Error("embedding provider unavailable"),
+ );
+ searchMocks.search.mockResolvedValue({
+ hits: [{ id: bookmark.id, score: 1 }],
+ totalHits: 1,
+ processingTimeMs: 1,
+ });
+
+ const result = await apiCallers[0].bookmarks.searchBookmarks({
+ text: "fallback",
+ searchMode: "hybrid",
+ });
+
+ expect(result.bookmarks.map((item) => item.id)).toEqual([bookmark.id]);
+ expect(searchMocks.search).toHaveBeenCalledTimes(2);
+ expect(searchMocks.vectorSearch).not.toHaveBeenCalled();
+ });
+
+ test<CustomTestContext>("falls back to full-text search for filter-only hybrid queries", async ({
+ apiCallers,
+ }) => {
+ const bookmark = await apiCallers[0].bookmarks.createBookmark({
+ type: BookmarkTypes.TEXT,
+ text: "favourited bookmark",
+ favourited: true,
+ });
+ mockEmbeddingInfra();
+ searchMocks.search.mockResolvedValue({
+ hits: [{ id: bookmark.id, score: 1 }],
+ totalHits: 1,
+ processingTimeMs: 1,
+ });
+
+ // A filter-only query has nothing to embed, so hybrid degrades to full-text
+ // search, which also means date sorting is allowed again.
+ const result = await apiCallers[0].bookmarks.searchBookmarks({
+ text: "is:fav",
+ searchMode: "hybrid",
+ sortOrder: "desc",
+ });
+
+ expect(result.bookmarks.map((item) => item.id)).toEqual([bookmark.id]);
+ expect(searchMocks.vectorSearch).not.toHaveBeenCalled();
+ });
+
+ test<CustomTestContext>("rejects filter-only semantic queries", async ({
+ apiCallers,
+ }) => {
+ mockEmbeddingInfra();
+
+ await expect(
+ apiCallers[0].bookmarks.searchBookmarks({
+ text: "is:fav",
+ searchMode: "semantic",
+ }),
+ ).rejects.toMatchObject({ code: "BAD_REQUEST" });
+ expect(searchMocks.vectorSearch).not.toHaveBeenCalled();
+ });
+
+ test<CustomTestContext>("rejects semantic search when its infrastructure is unavailable", async ({
+ apiCallers,
+ }) => {
+ searchMocks.buildInferenceClient.mockReturnValue(null);
+ searchMocks.getVectorStoreClient.mockResolvedValue(null);
+
+ await expect(
+ apiCallers[0].bookmarks.searchBookmarks({
+ text: "semantic query",
+ searchMode: "semantic",
+ }),
+ ).rejects.toMatchObject({ code: "BAD_REQUEST" });
+ });
+
+ test<CustomTestContext>("preserves semantic search runtime failures", async ({
+ apiCallers,
+ }) => {
+ mockEmbeddingInfra();
+ searchMocks.vectorSearch.mockRejectedValue(
+ new Error("vector query unavailable"),
+ );
+
+ await expect(
+ apiCallers[0].bookmarks.searchBookmarks({
+ text: "semantic query",
+ searchMode: "semantic",
+ }),
+ ).rejects.toThrow("vector query unavailable");
+ expect(searchMocks.search).not.toHaveBeenCalled();
+ });
+
+ test<CustomTestContext>("rejects date sorting for semantic and hybrid search", async ({
+ apiCallers,
+ }) => {
+ mockEmbeddingInfra();
+
+ await expect(
+ apiCallers[0].bookmarks.searchBookmarks({
+ text: "semantic query",
+ searchMode: "hybrid",
+ sortOrder: "desc",
+ }),
+ ).rejects.toMatchObject({ code: "BAD_REQUEST" });
+ });
+
+ test<CustomTestContext>("drops semantic hits below the similarity threshold", async ({
+ apiCallers,
+ }) => {
+ const bookmark = await apiCallers[0].bookmarks.createBookmark({
+ type: BookmarkTypes.TEXT,
+ text: "semantic result",
+ });
+ mockEmbeddingInfra();
+ searchMocks.vectorSearch.mockResolvedValue({
+ hits: [{ id: bookmark.id, score: 0.9 }],
+ processingTimeMs: 1,
+ });
+
+ const result = await apiCallers[0].bookmarks.searchBookmarks({
+ text: "meaningful query",
+ searchMode: "semantic",
+ });
+
+ expect(result.bookmarks.map((item) => item.id)).toEqual([bookmark.id]);
+ expect(searchMocks.vectorSearch).toHaveBeenCalledWith(
+ expect.objectContaining({ rankingScoreThreshold: 0.6 }),
+ );
+ expect(searchMocks.search).not.toHaveBeenCalled();
+ });
+});
diff --git a/packages/trpc/routers/bookmarks.ts b/packages/trpc/routers/bookmarks.ts
index e13a11a7..de965ee5 100644
--- a/packages/trpc/routers/bookmarks.ts
+++ b/packages/trpc/routers/bookmarks.ts
@@ -31,6 +31,7 @@ import {
import { SUPPORTED_BOOKMARK_ASSET_TYPES } from "@karakeep/shared/assetdb";
import serverConfig from "@karakeep/shared/config";
import { InferenceClientFactory } from "@karakeep/shared/inference";
+import logger from "@karakeep/shared/logger";
import { buildSummaryPrompt } from "@karakeep/shared/prompts.server";
import { EnqueueOptions } from "@karakeep/shared/queueing";
import { getRateLimitClient } from "@karakeep/shared/ratelimiting";
@@ -40,6 +41,7 @@ import type { ZBookmarkContent } from "@karakeep/shared/types/bookmarks";
import {
BookmarkTypes,
DEFAULT_NUM_BOOKMARKS_PER_PAGE,
+ MAX_NUM_BOOKMARKS_PER_PAGE,
zBookmarkSchema,
zBookmarkReadableContentFormatSchema,
zBookmarkReadableContentSchema,
@@ -54,6 +56,8 @@ import {
import type { ZBookmarkTags } from "@karakeep/shared/types/tags";
import { ANCHOR_TEXT_MAX_LENGTH } from "@karakeep/shared/utils/reading-progress-dom";
import { normalizeTagName } from "@karakeep/shared/utils/tag";
+import { getVectorStoreClient } from "@karakeep/shared/vectorStore";
+import type { VectorFilterQuery } from "@karakeep/shared/vectorStore";
import { bookmarkCreationCounter } from "../stats";
import type { AuthedContext } from "../index";
@@ -66,11 +70,20 @@ import {
} from "../index";
import { RuleEngine } from "../lib/ruleEngine";
import { getBookmarkIdsFromMatcher } from "../lib/search";
+import { reciprocalRankFusion } from "../lib/searchRanking";
import { Asset } from "../models/assets";
import { BareBookmark, Bookmark } from "../models/bookmarks";
import { WebhooksService } from "../models/webhooks.service";
const bookmarksProcedure = createScopedAuthedProcedure("bookmarks");
+const HYBRID_CANDIDATES_PER_SOURCE = MAX_NUM_BOOKMARKS_PER_PAGE;
+/**
+ * Vector search always returns as many hits as it's asked for, so without a
+ * floor an unrelated query still fills a whole page with noise. Vector stores
+ * normalize similarity into a 0..1 ranking score (for cosine distance that's
+ * `(1 + cosine) / 2`), so this drops anything below ~0.2 cosine similarity.
+ */
+const SEMANTIC_SCORE_THRESHOLD = 0.6;
export const ensureBookmarkOwnership = experimental_trpcMiddleware<{
ctx: AuthedContext;
@@ -126,6 +139,11 @@ async function attemptToDedupLink(ctx: AuthedContext, url: string) {
}
const BOOKMARKS_QUERIED_WINDOW_MS = 10 * 60 * 1000;
+const semanticSearchRateLimitConfig = {
+ name: "bookmarks.searchBookmarks.semantic",
+ windowMs: 60 * 1000,
+ maxRequests: 300,
+} as const;
function createBookmarksQueriedMiddleware<T>() {
return async function bookmarksQueriedMiddleware(opts: {
@@ -142,6 +160,28 @@ function createBookmarksQueriedMiddleware<T>() {
};
}
+export function createSemanticSearchRateLimitMiddleware<T>() {
+ const rateLimitMiddleware = createRateLimitMiddleware<T>(
+ semanticSearchRateLimitConfig,
+ );
+ return function semanticSearchRateLimitMiddleware(opts: {
+ path: string;
+ ctx: {
+ req: { ip: string | null };
+ user: { id: string };
+ };
+ input: {
+ searchMode: "fts" | "semantic" | "hybrid";
+ };
+ next: () => Promise<T>;
+ }) {
+ if (opts.input.searchMode === "fts") {
+ return opts.next();
+ }
+ return rateLimitMiddleware(opts);
+ };
+}
+
function safeUrlHost(url: string | undefined): string | undefined {
if (!url) {
return undefined;
@@ -834,6 +874,7 @@ export const bookmarksAppRouter = router({
.use(createBookmarksQueriedMiddleware())
.use(createEventLogMiddleware("search.query"))
.input(zSearchBookmarksRequestSchema)
+ .use(createSemanticSearchRateLimitMiddleware())
.output(
z.object({
bookmarks: z.array(zBookmarkSchema),
@@ -843,18 +884,10 @@ export const bookmarksAppRouter = router({
.query(async ({ input, ctx }) => {
addLogFields<"search.query">({
"search.has_query": input.text.length > 0,
+ "search.mode": input.searchMode,
});
- if (!input.limit) {
- input.limit = DEFAULT_NUM_BOOKMARKS_PER_PAGE;
- }
+ const limit = input.limit ?? DEFAULT_NUM_BOOKMARKS_PER_PAGE;
const sortOrder = input.sortOrder || "relevance";
- const client = await getSearchClient();
- if (!client) {
- throw new TRPCError({
- code: "INTERNAL_SERVER_ERROR",
- message: "Search functionality is not configured",
- });
- }
const parsedQuery = parseSearchQuery(input.text);
let filter: FilterQuery[];
@@ -876,32 +909,168 @@ export const bookmarksAppRouter = router({
*/
const createdAtSortOrder = sortOrder === "relevance" ? "desc" : sortOrder;
- const resp = await client.search({
- query: parsedQuery.text,
- filter,
- sort: [{ field: "createdAt", order: createdAtSortOrder }],
- limit: input.limit,
- ...(input.cursor
- ? {
- offset: input.cursor.offset,
- }
- : {}),
+ const offset = input.cursor?.offset ?? 0;
+ let hits: { id: string; score: number }[];
+ let hasMore: boolean;
+ let resultCount: number;
+
+ const fullTextSearch = async (limit: number, searchOffset?: number) => {
+ const client = await getSearchClient();
+ if (!client) {
+ throw new TRPCError({
+ code: "INTERNAL_SERVER_ERROR",
+ message: "Search functionality is not configured",
+ });
+ }
+ return client.search({
+ query: parsedQuery.text,
+ filter,
+ sort: [{ field: "createdAt", order: createdAtSortOrder }],
+ limit,
+ ...(searchOffset !== undefined ? { offset: searchOffset } : {}),
+ });
+ };
+
+ const fullTextPage = (
+ resp: Awaited<ReturnType<typeof fullTextSearch>>,
+ ) => ({
+ hits: resp.hits.map((hit) => ({
+ id: hit.id,
+ score: hit.score ?? 0,
+ })),
+ hasMore: offset + resp.hits.length < resp.totalHits,
+ resultCount: resp.totalHits,
});
+ const degradeToFullTextSearch = async (error?: unknown) => {
+ addLogFields<"search.query">({ "search.degraded": true });
+ if (error) {
+ const message = error instanceof Error ? error.message : `${error}`;
+ logger.warn(
+ `Hybrid semantic search failed; falling back to full-text search: ${message}`,
+ );
+ }
+ return fullTextPage(await fullTextSearch(limit, offset));
+ };
+
+ if (input.searchMode === "fts") {
+ ({ hits, hasMore, resultCount } = fullTextPage(
+ await fullTextSearch(limit, offset),
+ ));
+ } else {
+ // A query made up entirely of qualifiers (e.g. `is:fav`) has nothing to
+ // embed, so it can only be served by full-text search.
+ const hasQueryText = parsedQuery.text.trim().length > 0;
+ let semanticInfraError: unknown;
+ const semanticClients = await (async () => ({
+ inferenceClient: InferenceClientFactory.build(),
+ vectorStoreClient: await getVectorStoreClient(),
+ }))().catch((error: unknown) => {
+ if (input.searchMode === "semantic") {
+ throw error;
+ }
+ semanticInfraError = error;
+ return null;
+ });
+ const inferenceClient = semanticClients?.inferenceClient;
+ const vectorStoreClient = semanticClients?.vectorStoreClient;
+ if (!hasQueryText || !inferenceClient || !vectorStoreClient) {
+ if (input.searchMode === "semantic") {
+ throw new TRPCError({
+ code: "BAD_REQUEST",
+ message: hasQueryText
+ ? "Semantic search requires configured inference and vector store providers"
+ : "Semantic search requires a non-empty text query",
+ });
+ }
+
+ // Hybrid search remains useful when embeddings are unavailable or
+ // when there's no text to embed. It degrades to plain full-text
+ // search, which also means date sorting is supported again.
+ ({ hits, hasMore, resultCount } =
+ await degradeToFullTextSearch(semanticInfraError));
+ } else {
+ if (sortOrder !== "relevance") {
+ throw new TRPCError({
+ code: "BAD_REQUEST",
+ message:
+ "Semantic and hybrid search only support relevance sorting",
+ });
+ }
+
+ const vectorFilter: VectorFilterQuery[] = filter.map((item) =>
+ item.type === "eq"
+ ? { type: "eq", field: item.field, value: item.value }
+ : { type: "in", field: item.field, values: item.values },
+ );
+
+ const semanticSearch = async (limit: number) => {
+ const embeddingResponse =
+ await inferenceClient.generateEmbeddingFromText([
+ parsedQuery.text,
+ ]);
+ const vector = embeddingResponse.embeddings[0];
+ if (!vector) {
+ throw new TRPCError({
+ code: "INTERNAL_SERVER_ERROR",
+ message: "Inference provider returned no query embedding",
+ });
+ }
+ return vectorStoreClient.search({
+ vector,
+ filter: vectorFilter,
+ limit,
+ rankingScoreThreshold: SEMANTIC_SCORE_THRESHOLD,
+ });
+ };
+
+ if (input.searchMode === "semantic") {
+ const semanticLimit = offset + limit + 1;
+ const semanticResp = await semanticSearch(semanticLimit);
+ hits = semanticResp.hits.slice(offset, offset + limit);
+ hasMore = semanticResp.hits.length > offset + limit;
+ resultCount = semanticResp.hits.length;
+ } else {
+ // RRF can reorder earlier pages when its input window grows. Fuse a
+ // fixed window so every cursor sees the same ranked candidate pool.
+ const [ftsResult, semanticResult] = await Promise.allSettled([
+ fullTextSearch(HYBRID_CANDIDATES_PER_SOURCE),
+ semanticSearch(HYBRID_CANDIDATES_PER_SOURCE),
+ ]);
+ if (ftsResult.status === "rejected") {
+ throw ftsResult.reason;
+ }
+ if (semanticResult.status === "rejected") {
+ ({ hits, hasMore, resultCount } = await degradeToFullTextSearch(
+ semanticResult.reason,
+ ));
+ } else {
+ const fusedHits = reciprocalRankFusion([
+ ftsResult.value.hits,
+ semanticResult.value.hits,
+ ]);
+ hits = fusedHits.slice(offset, offset + limit);
+ hasMore = fusedHits.length > offset + limit;
+ resultCount = fusedHits.length;
+ }
+ }
+ }
+ }
+
addLogFields<"search.query">({
- "search.results_count": resp.totalHits,
+ "search.results_count": resultCount,
});
- if (resp.hits.length == 0) {
+ if (hits.length == 0) {
return { bookmarks: [], nextCursor: null };
}
- const idToRank = resp.hits.reduce<Record<string, number>>((acc, r) => {
- acc[r.id] = r.score || 0;
+ const idToRank = hits.reduce<Record<string, number>>((acc, r) => {
+ acc[r.id] = r.score;
return acc;
}, {});
const { bookmarks: results } = await Bookmark.loadMulti(ctx, {
- ids: resp.hits.map((h) => h.id),
+ ids: hits.map((h) => h.id),
includeContent: input.includeContent,
sortOrder: "desc", // Doesn't matter, we're sorting again afterwards and the list contain all data
});
@@ -920,13 +1089,12 @@ export const bookmarksAppRouter = router({
return {
bookmarks: results.map((b) => b.asZBookmark()),
- nextCursor:
- resp.hits.length + (input.cursor?.offset || 0) >= resp.totalHits
- ? null
- : {
- ver: 1 as const,
- offset: resp.hits.length + (input.cursor?.offset || 0),
- },
+ nextCursor: hasMore
+ ? {
+ ver: 1 as const,
+ offset: offset + hits.length,
+ }
+ : null,
};
}),
checkUrl: bookmarksProcedure