Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
feat(open-knowledge): bias @mention autocomplete toward page context (#2116)
Andrew Mikofalvya75181977f8e
diff --git a/.changeset/wiki-link-mention-ranking.md b/.changeset/wiki-link-mention-ranking.mdnew file mode 100644index 000000000..a4f37ae8e--- /dev/null+++ b/.changeset/wiki-link-mention-ranking.md@@ -0,0 +1,5 @@+---+"@inkeep/open-knowledge-app": patch+---++Improve `[[` wiki-link ("@mention") autocomplete ranking to surface the most relevant link targets first. The page you're editing and its link-graph neighbors (incoming and outgoing links) are now boosted, so opening the picker leads with the pages you're most likely to link to; docs under skill/tooling folders (`.agents`, `.claude`, `.cursor`) are deprioritized as knowledge-base noise (deprioritized, not hidden — a skill still appears when it's the best match). Both the WYSIWYG and the source-mode `[[` pickers re-rank in lockstep. Ranking for the command palette, full-text, and MCP search is unchanged.diff --git a/packages/app/src/editor/SourceEditor.tsx b/packages/app/src/editor/SourceEditor.tsxindex 4d9a548ce..e732ff1f6 100644--- a/packages/app/src/editor/SourceEditor.tsx+++ b/packages/app/src/editor/SourceEditor.tsx@@ -153,6 +153,7 @@ export function SourceEditor({ydoc: provider.document,wordWrapCompartment,wordWrap,+ currentDocName: resolvedDocName,}),createSourcePolishExtension(),sourceClipboard,diff --git a/packages/app/src/editor/extensions/nested-cm-extensions.ts b/packages/app/src/editor/extensions/nested-cm-extensions.tsindex 9f1763549..57cc8f584 100644--- a/packages/app/src/editor/extensions/nested-cm-extensions.ts+++ b/packages/app/src/editor/extensions/nested-cm-extensions.ts@@ -93,6 +93,7 @@ interface NestedCMOptions {wordWrapCompartment?: Compartment;wordWrap?: boolean;extraKeymaps?: Extension;+ currentDocName?: string | null;}export function createNestedCMExtensions(options: NestedCMOptions): Extension[] {@@ -102,7 +103,7 @@ export function createNestedCMExtensions(options: NestedCMOptions): Extension[]return [markdown({ base: markdownLanguage, extensions: [GFM], codeLanguages }),- createWikiLinkSourceExtension(),+ createWikiLinkSourceExtension(options.currentDocName ?? null),createMdLinkSourceExtension(),...(ydoc ? [createAgentFlashSourceExtension(ydoc)] : []),keymap.of([]),diff --git a/packages/app/src/editor/extensions/wiki-link-suggestion.test.ts b/packages/app/src/editor/extensions/wiki-link-suggestion.test.tsindex 2872ffdad..cdba3b948 100644--- a/packages/app/src/editor/extensions/wiki-link-suggestion.test.ts+++ b/packages/app/src/editor/extensions/wiki-link-suggestion.test.ts@@ -1,12 +1,17 @@import { afterEach, beforeEach, describe, expect, mock, test } from 'bun:test';import type { HeadingEntry } from '@inkeep/open-knowledge-core';import {+ autocompleteBoost,buildAnchorItems,buildSuggestionItems,computeFallbackAttrs,fetchPages,+ filterPages,+ isSkillFolderDoc,+ loadWikiLinkContext,type PageItem,parseQuery,+ type WikiLinkContext,wikiLinkMatcher,} from './wiki-link-suggestion';@@ -369,3 +374,223 @@ describe('fetchPages', () => {expect(result.some((item) => item.kind === 'folder')).toBe(false);});});++describe('isSkillFolderDoc', () => {+ test('matches docs under .agents / .claude / .cursor at any depth', () => {+ expect(isSkillFolderDoc('.claude/skills/foo/SKILL')).toBe(true);+ expect(isSkillFolderDoc('.agents/rules/bar')).toBe(true);+ expect(isSkillFolderDoc('.cursor/rules/baz')).toBe(true);+ expect(isSkillFolderDoc('public/open-knowledge/.claude/skills/x')).toBe(true);+ });++ test('does not match ordinary docs or look-alike folder names', () => {+ expect(isSkillFolderDoc('guides/getting-started')).toBe(false);+ expect(isSkillFolderDoc('claude/notes')).toBe(false); // no leading dot+ expect(isSkillFolderDoc('agents-overview')).toBe(false);+ });+});++describe('autocompleteBoost', () => {+ const ctx = (over: Partial<WikiLinkContext> = {}): WikiLinkContext => ({+ currentDocName: null,+ connectedDocNames: new Set(),+ ...over,+ });++ test('penalizes skill-folder docs', () => {+ expect(autocompleteBoost('.claude/skills/foo/SKILL', ctx())).toBe(-200);+ });++ test('boosts the current page and link-graph neighbors, neighbor > current', () => {+ expect(autocompleteBoost('current', ctx({ currentDocName: 'current' }))).toBe(50);+ expect(autocompleteBoost('neighbor', ctx({ connectedDocNames: new Set(['neighbor']) }))).toBe(+ 100,+ );+ });++ test('combines penalty and link boost additively (a linked skill is still demoted)', () => {+ const linkedSkill = autocompleteBoost(+ '.claude/skills/foo/SKILL',+ ctx({ connectedDocNames: new Set(['.claude/skills/foo/SKILL']) }),+ );+ expect(linkedSkill).toBe(-100);+ });++ test('returns 0 for an ordinary doc with empty context', () => {+ expect(autocompleteBoost('guides/intro', ctx())).toBe(0);+ });+});++describe('context-aware ranking', () => {+ test('empty query: neighbors and current page float up, skills sink', () => {+ const corpus: PageItem[] = [+ { docName: 'alpha', title: 'Alpha' },+ { docName: '.claude/skills/foo/SKILL', title: 'Foo' },+ { docName: 'beta', title: 'Beta' },+ { docName: 'gamma', title: 'Gamma' },+ ];+ const context: WikiLinkContext = {+ currentDocName: 'beta',+ connectedDocNames: new Set(['gamma']),+ };+ expect(filterPages(corpus, '', context).map((p) => p.docName)).toEqual([+ 'gamma', // linked neighbor (+100)+ 'beta', // current page (+50)+ 'alpha', // ordinary (0)+ '.claude/skills/foo/SKILL', // skill (-200)+ ]);+ });++ test('empty query without context preserves source order (byte-identical to slice)', () => {+ const corpus: PageItem[] = [+ { docName: 'alpha', title: 'Alpha' },+ { docName: 'beta', title: 'Beta' },+ { docName: 'gamma', title: 'Gamma' },+ ];+ expect(filterPages(corpus, '').map((p) => p.docName)).toEqual(['alpha', 'beta', 'gamma']);+ });++ test('typed query: a skill is deprioritized below a stronger non-skill match but still listed', () => {+ const corpus: PageItem[] = [+ { docName: '.claude/skills/notes/SKILL', title: 'Project notes overview' },+ { docName: 'notes', title: 'Notes' },+ ];+ expect(filterPages(corpus, 'notes').map((p) => p.docName)).toEqual([+ 'notes',+ '.claude/skills/notes/SKILL',+ ]);+ });++ test('typed query: a linked neighbor outranks an equal-tier non-linked match', () => {+ const corpus: PageItem[] = [+ { docName: 'guide-alpha', title: 'Guide alpha' },+ { docName: 'guide-beta', title: 'Guide beta' },+ ];+ const context: WikiLinkContext = {+ currentDocName: 'somewhere-else',+ connectedDocNames: new Set(['guide-beta']),+ };+ expect(filterPages(corpus, 'guide', context).map((p) => p.docName)).toEqual([+ 'guide-beta',+ 'guide-alpha',+ ]);+ });++ test('typed query: a boosted neighbor ranked outside the natural top-8 still surfaces', () => {+ const corpus: PageItem[] = Array.from({ length: 9 }, (_, i) => ({+ docName: `item-${i + 1}`,+ title: `Item ${i + 1}`,+ }));+ const noContext = filterPages(corpus, 'item').map((p) => p.docName);+ expect(noContext).toHaveLength(8);+ expect(noContext).not.toContain('item-9');++ const withNeighbor = filterPages(corpus, 'item', {+ currentDocName: 'elsewhere',+ connectedDocNames: new Set(['item-9']),+ }).map((p) => p.docName);+ expect(withNeighbor).toContain('item-9');+ });+});++describe('loadWikiLinkContext', () => {+ const realFetch = globalThis.fetch;++ function stubLinks(routes: {+ forward?: { status?: number; body: unknown };+ back?: { status?: number; body: unknown };+ }) {+ globalThis.fetch = mock(async (input: RequestInfo | URL) => {+ const url = typeof input === 'string' ? input : input.toString();+ const route = url.startsWith('/api/forward-links')+ ? routes.forward+ : url.startsWith('/api/backlinks')+ ? routes.back+ : undefined;+ const status = route?.status ?? (route ? 200 : 404);+ return new Response(JSON.stringify(route?.body ?? {}), {+ status,+ headers: { 'content-type': 'application/json' },+ });+ }) as typeof globalThis.fetch;+ }++ afterEach(() => {+ globalThis.fetch = realFetch;+ });++ test('returns an empty context for a null docName without fetching', async () => {+ let called = false;+ globalThis.fetch = mock(async () => {+ called = true;+ return new Response('{}', { status: 200 });+ }) as typeof globalThis.fetch;+ const ctx = await loadWikiLinkContext(null);+ expect(ctx).toEqual({ currentDocName: null, connectedDocNames: new Set() });+ expect(called).toBe(false);+ });++ test('merges outgoing doc links with incoming sources and excludes external links', async () => {+ stubLinks({+ forward: {+ body: {+ docName: 'me',+ forwardLinks: [+ { kind: 'doc', docName: 'out-a', anchor: null, title: 'A', snippet: null },+ { kind: 'external', url: 'https://example.com', title: 'x', snippet: null },+ ],+ },+ },+ back: {+ body: {+ docName: 'me',+ backlinks: [{ source: 'in-b', anchor: null, title: 'B', snippet: null }],+ },+ },+ });+ const ctx = await loadWikiLinkContext('me');+ expect(ctx.currentDocName).toBe('me');+ expect([...ctx.connectedDocNames].sort()).toEqual(['in-b', 'out-a']);+ });++ test('drops a self-link so the current page earns the current-page boost, not the neighbor boost', async () => {+ stubLinks({+ forward: {+ body: {+ docName: 'me',+ forwardLinks: [+ { kind: 'doc', docName: 'me', anchor: null, title: 'self', snippet: null },+ { kind: 'doc', docName: 'friend', anchor: null, title: 'F', snippet: null },+ ],+ },+ },+ back: { body: { docName: 'me', backlinks: [] } },+ });+ const ctx = await loadWikiLinkContext('me');+ expect(ctx.connectedDocNames.has('me')).toBe(false);+ expect(autocompleteBoost('me', ctx)).toBe(50);+ expect(autocompleteBoost('friend', ctx)).toBe(100);+ });++ test('degrades to the still-successful side when one endpoint errors (HTTP 500)', async () => {+ stubLinks({+ forward: { status: 500, body: {} },+ back: {+ body: {+ docName: 'me',+ backlinks: [{ source: 'in-b', anchor: null, title: 'B', snippet: null }],+ },+ },+ });+ const ctx = await loadWikiLinkContext('me');+ expect(ctx.currentDocName).toBe('me');+ expect([...ctx.connectedDocNames]).toEqual(['in-b']);+ });++ test('degrades to no neighbors when a response body is malformed', async () => {+ stubLinks({ forward: { body: { wrong: 'shape' } }, back: { body: { nope: true } } });+ const ctx = await loadWikiLinkContext('me');+ expect(ctx.currentDocName).toBe('me');+ expect(ctx.connectedDocNames.size).toBe(0);+ });+});diff --git a/packages/app/src/editor/extensions/wiki-link-suggestion.ts b/packages/app/src/editor/extensions/wiki-link-suggestion.tsindex 8eaa4c034..629cebe89 100644--- a/packages/app/src/editor/extensions/wiki-link-suggestion.ts+++ b/packages/app/src/editor/extensions/wiki-link-suggestion.ts@@ -1,7 +1,10 @@import {+ BacklinksSuccessSchema,createWorkspaceSearchCorpus,createWorkspaceSearchDocument,+ ForwardLinksSuccessSchema,type HeadingEntry,+ MAX_WORKSPACE_SEARCH_LIMIT,PageHeadingsSuccessSchema,PagesSuccessSchema,ProblemDetailsSchema,@@ -15,6 +18,7 @@ import { ReactRenderer } from '@tiptap/react';import Suggestion, { type SuggestionKeyDownProps, type SuggestionProps } from '@tiptap/suggestion';import { HttpResponseParseError } from '../http-client';import { WikiLinkSuggestionMenu } from '../wiki-link-suggestion/WikiLinkSuggestionMenu';+import { getEditorDocName } from './doc-context';import { getEditorSourceMode } from './editor-mode-context';import {createSuggestionPopup,@@ -45,6 +49,37 @@ interface ParsedQuery {const MAX_ITEMS = 8;+export interface WikiLinkContext {+ currentDocName: string | null;+ connectedDocNames: ReadonlySet<string>;+}++const EMPTY_WIKI_LINK_CONTEXT: WikiLinkContext = {+ currentDocName: null,+ connectedDocNames: new Set(),+};++const SKILL_FOLDER_SEGMENTS: ReadonlySet<string> = new Set(['.agents', '.claude', '.cursor']);++const SKILL_FOLDER_PENALTY = 200;+const LINK_GRAPH_BOOST = 100;+const CURRENT_PAGE_BOOST = 50;++export function isSkillFolderDoc(docName: string): boolean {+ return docName.split('/').some((segment) => SKILL_FOLDER_SEGMENTS.has(segment));+}++export function autocompleteBoost(docName: string, context: WikiLinkContext): number {+ let boost = 0;+ if (isSkillFolderDoc(docName)) boost -= SKILL_FOLDER_PENALTY;+ if (context.currentDocName !== null && docName === context.currentDocName) {+ boost += CURRENT_PAGE_BOOST;+ } else if (context.connectedDocNames.has(docName)) {+ boost += LINK_GRAPH_BOOST;+ }+ return boost;+}+interface SuggestionSearchCorpus<T> {fingerprint: string;byPath: ReadonlyMap<string, T>;@@ -66,14 +101,33 @@ export function parseQuery(query: string): ParsedQuery {return { mode: 'page', pageTarget: '', anchorQuery: '' };}-export function filterPages(pages: PageItem[], query: string): PageItem[] {- if (!query) return pages.slice(0, MAX_ITEMS);+export function filterPages(+ pages: PageItem[],+ query: string,+ context: WikiLinkContext = EMPTY_WIKI_LINK_CONTEXT,+): PageItem[] {+ if (!query) {+ return pages+ .map((page, index) => ({ page, index, boost: autocompleteBoost(page.docName, context) }))+ .sort((a, b) => b.boost - a.boost || a.index - b.index)+ .slice(0, MAX_ITEMS)+ .map((entry) => entry.page);+ }const searchCorpus = getCachedPageSearchCorpus(pages);return searchWorkspaceCorpus(searchCorpus.corpus, query, {intent: 'autocomplete',- limit: MAX_ITEMS,+ limit: MAX_WORKSPACE_SEARCH_LIMIT,})- .map((result) => searchCorpus.byPath.get(result.document.path))+ .map((result) => ({+ result,+ adjusted: result.score + autocompleteBoost(result.document.path, context),+ }))+ .sort(+ (a, b) =>+ b.adjusted - a.adjusted || a.result.document.path.localeCompare(b.result.document.path),+ )+ .slice(0, MAX_ITEMS)+ .map((entry) => searchCorpus.byPath.get(entry.result.document.path)).filter((page) => !!page);}@@ -132,8 +186,12 @@ export function filterHeadings(headings: HeadingEntry[], anchorQuery: string): H.filter((heading) => !!heading);}-export function buildSuggestionItems(pages: PageItem[], query: string): WikiLinkSuggestionItem[] {- const filtered = filterPages(pages, query);+export function buildSuggestionItems(+ pages: PageItem[],+ query: string,+ context: WikiLinkContext = EMPTY_WIKI_LINK_CONTEXT,+): WikiLinkSuggestionItem[] {+ const filtered = filterPages(pages, query, context);if (filtered.length > 0) {return filtered.map((item) =>item.kind === 'asset'@@ -289,10 +347,55 @@ export async function fetchHeadings(docName: string): Promise<HeadingEntry[]> {return success.data.headings ?? [];}+async function fetchForwardLinkTargets(docName: string): Promise<string[]> {+ try {+ const r = await fetch(`/api/forward-links?docName=${encodeURIComponent(docName)}`);+ if (!r.ok) {+ console.warn('[wiki-link-suggestion] /api/forward-links responded', r.status, docName);+ return [];+ }+ const success = ForwardLinksSuccessSchema.safeParse(await r.json());+ if (!success.success) return [];+ return success.data.forwardLinks.flatMap((link) => (link.kind === 'doc' ? [link.docName] : []));+ } catch (err) {+ console.warn('[wiki-link-suggestion] Failed to fetch forward links:', err);+ return [];+ }+}++async function fetchBacklinkSources(docName: string): Promise<string[]> {+ try {+ const r = await fetch(`/api/backlinks?docName=${encodeURIComponent(docName)}`);+ if (!r.ok) {+ console.warn('[wiki-link-suggestion] /api/backlinks responded', r.status, docName);+ return [];+ }+ const success = BacklinksSuccessSchema.safeParse(await r.json());+ if (!success.success) return [];+ return success.data.backlinks.map((link) => link.source);+ } catch (err) {+ console.warn('[wiki-link-suggestion] Failed to fetch backlinks:', err);+ return [];+ }+}++export async function loadWikiLinkContext(currentDocName: string | null): Promise<WikiLinkContext> {+ if (!currentDocName) return EMPTY_WIKI_LINK_CONTEXT;+ const [outgoing, incoming] = await Promise.all([+ fetchForwardLinkTargets(currentDocName),+ fetchBacklinkSources(currentDocName),+ ]);+ const connectedDocNames = new Set<string>([...outgoing, ...incoming]);+ connectedDocNames.delete(currentDocName);+ return { currentDocName, connectedDocNames };+}+export function configureWikiLinkSuggestion(editor: Editor) {let cachedPages: PageItem[] = [];let pagesLoaded = false;let pagesPromise: Promise<PageItem[]> | null = null;+ let cachedContext: WikiLinkContext = EMPTY_WIKI_LINK_CONTEXT;+ let contextPromise: Promise<WikiLinkContext> | null = null;let cachedHeadings = new Map<string, HeadingEntry[]>();let anchorFetchingFor: string | null = null;let fetchError: string | null = null;@@ -330,20 +433,31 @@ export function configureWikiLinkSuggestion(editor: Editor) {if (!pagesLoaded) {pagesPromise ||= fetchPages();- try {- cachedPages = await pagesPromise;+ contextPromise ||= loadWikiLinkContext(getEditorDocName(editor));+ const [pagesResult, contextResult] = await Promise.allSettled([+ pagesPromise,+ contextPromise,+ ]);+ if (pagesResult.status === 'fulfilled') {+ cachedPages = pagesResult.value;fetchError = null;- } catch (err) {- console.error('[wiki-link-suggestion] Failed to fetch pages:', err);+ } else {+ console.error('[wiki-link-suggestion] Failed to fetch pages:', pagesResult.reason);fetchError ='Failed to load pages. Press Escape and type [[ again to retry, or continue typing to insert an unresolved link.';cachedPages = [];- } finally {- pagesLoaded = true;- pagesPromise = null;}+ if (contextResult.status === 'fulfilled') {+ cachedContext = contextResult.value;+ } else {+ console.warn('[wiki-link-suggestion] link context load rejected:', contextResult.reason);+ cachedContext = EMPTY_WIKI_LINK_CONTEXT;+ }+ pagesLoaded = true;+ pagesPromise = null;+ contextPromise = null;}- return buildSuggestionItems(cachedPages, query);+ return buildSuggestionItems(cachedPages, query, cachedContext);},command: ({ editor, range, props: item }) => {@@ -514,11 +628,13 @@ export function configureWikiLinkSuggestion(editor: Editor) {currentProps = null;selectedIndex = 0;cachedPages = [];+ cachedContext = EMPTY_WIKI_LINK_CONTEXT;cachedHeadings = new Map();fetchError = null;anchorFetchError = null;pagesLoaded = false;pagesPromise = null;+ contextPromise = null;anchorFetchingFor = null;},};diff --git a/packages/app/src/editor/plugins/wiki-link-source.ts b/packages/app/src/editor/plugins/wiki-link-source.tsindex ae537c02e..6143f95fa 100644--- a/packages/app/src/editor/plugins/wiki-link-source.ts+++ b/packages/app/src/editor/plugins/wiki-link-source.ts@@ -16,7 +16,9 @@ import {fetchPages,filterHeadings,filterPages,+ loadWikiLinkContext,type PageItem,+ type WikiLinkContext,} from '../extensions/wiki-link-suggestion';import {openHashHrefInNewTab,@@ -30,6 +32,17 @@ let pagesCache: PageItem[] | null = null;let pagesCacheTime = 0;let knownTargetSet: Set<string> | null = null;const headingsCache = new Map<string, { headings: HeadingEntry[]; time: number }>();+const contextCache = new Map<string, { context: WikiLinkContext; time: number }>();++async function getWikiLinkContext(docName: string | null): Promise<WikiLinkContext> {+ if (!docName) return loadWikiLinkContext(null);+ const now = Date.now();+ const cached = contextCache.get(docName);+ if (cached !== undefined && now - cached.time < PAGES_CACHE_TTL_MS) return cached.context;+ const context = await loadWikiLinkContext(docName);+ contextCache.set(docName, { context, time: now });+ return context;+}async function getPages(): Promise<PageItem[]> {const now = Date.now();@@ -214,6 +227,7 @@ const wikiLinkClickHandler = EditorView.domEventHandlers({async function wikiLinkCompletionSource(context: CompletionContext,+ currentDocName: string | null,): Promise<CompletionResult | null> {const textBefore = context.state.doc.sliceString(0, context.pos);@@ -252,11 +266,14 @@ async function wikiLinkCompletionSource(};}- const pages = await getPages().catch((err) => {- console.warn('[wiki-link-source] Failed to fetch pages:', err);- return [] as PageItem[];- });- const filtered = filterPages(pages, query);+ const [pages, linkContext] = await Promise.all([+ getPages().catch((err) => {+ console.warn('[wiki-link-source] Failed to fetch pages:', err);+ return [] as PageItem[];+ }),+ getWikiLinkContext(currentDocName),+ ]);+ const filtered = filterPages(pages, query, linkContext);return {from: triggerPos,@@ -287,11 +304,14 @@ const wikiLinkTheme = EditorView.theme({},});-export function createWikiLinkSourceExtension(): Extension {+export function createWikiLinkSourceExtension(currentDocName: string | null = null): Extension {return [wikiLinkDecorations,wikiLinkClickHandler,wikiLinkTheme,- markdownLanguage.data.of({ autocomplete: wikiLinkCompletionSource }),+ markdownLanguage.data.of({+ autocomplete: (context: CompletionContext) =>+ wikiLinkCompletionSource(context, currentDocName),+ }),];}