Skip to content
Hussh
Connect MCP

Wiki search — dual-audience UX + AX (R&D)

Has anyone shipped a wiki search interface optimized for both humans (UX) and agents (AX)? Survey of the design space and the few existing examples.

About Wiki

Wiki search — dual-audience (UX + AX)

TL;DR: No one has shipped a fully-mature wiki search interface that is best-in-class for both humans (UX) and AI agents (AX). The category is real, the discipline now has a name (Agent Experience / AX, coined by Netlify CEO Matt Biilmann in early 2025), and the leading patterns are converging — but the existing tools each excel on one side and retrofit the other. The best dual-audience example we found is Synapse (a Neo4j ↔ Notion bidirectional sync via MCP) and the cleanest production-grade single-backend pair is qmd CLI + qmd MCP + qmd Raycast extension. Hussh's current wiki has strong AX (markdown files Claude reads natively) and weak UX (no editor configured). The cheapest dual upgrade: open the vault in Obsidian for humans and add cyanheads/obsidian-mcp-server for agents — both work against the same files, no sync layer. Status as of 2026-05-03: Initial R&D pass. Not implemented.

Relations

  • LLM Wiki pattern — landscape & R&D — the parent pattern this builds on.
  • A schema page at the wiki root encodes our conventions (private).
  • An open-questions ledger tracks pending research tasks of the kind this surface would help with (private).

1. The discipline: AX as a peer to UX

Agent Experience (AX) = "the holistic experience AI agents will have as the user of a product or platform" — Matt Biilmann (Netlify), early 2025. Adopted by Netlify, WorkOS, Stytch, Resend, Clerk, Auth0, Neon, Vite, Daytona within months. Now a top-line design discipline: John Maeda's Design in Tech Report 2026 frames it "from UX to AX".

Position relative to existing disciplines:

  • UX (Don Norman, 1993) — humans interacting with systems.
  • DX (Jeremiah Lee, 2011) — developers interacting with platforms.
  • AX (Biilmann, 2025) — autonomous agents interacting with products.

Additive, not subtractive. The accessibility lens carries over: "most accessibility practices for humans also improve agent effectiveness" — same content tree, same semantic markup, same predictability. (Pixelmojo guide.)

Biilmann's framing of AX has four implicit dimensions (Pixelmojo formalizes them as Access / Context / Tools / Orchestration):

  • Access — can the agent reach the operations? Auth, scopes, deterministic URLs.
  • Context — does the agent have machine-readable docs, schemas, examples, llms.txt?
  • Tools — clean APIs/MCP servers exposing operations the agent can compose.
  • Orchestration — collaborative human-in-the-loop workflows with approval, undo, escalation.

2. The design space for a wiki search interface

Different audiences want different things from the same underlying search:

DimensionHuman (UX)Agent (AX)
Latency<200ms feels instant<2s is fine if structured
OutputVisual cards, snippets, highlightsJSON with stable schema, line numbers, source paths
Ranking explainability"Why this result?" badgePer-result confidence score + reasoning
NavigationClick → page → backlinks → graph viewTool call → page contents → follow-up tool calls
DisambiguationSuggest-as-you-type, facetsStrict query language; no implicit assumptions
Side-effectsOpen the page, scroll to matchReturn JSON; let the agent decide what to do
OnboardingDiscoverable, forgivingSchema-introspectable, idempotent, well-documented
TrustSource attribution visible at a glanceCitations as structured fields, not prose
ScalePagination, infinite scrollpageSize / pageToken / next_page_token

Both sides want: same backend, same authoritative ranking, same access controls, same data model. The split is purely at the surface.

3. What exists today — by approach

3a. Same files, two clients (zero sync)

The dominant pattern in 2026. Both human UI and agent operate on plain markdown files.

  • Obsidian (human) + Claude Code (agent) on the same vault — this is what aimaker.substack and Manav Ghosh's walkthrough recommend. This is what the Hussh wiki could be in 5 minutes. Pros: zero sync, file system is the single source of truth, git-friendly. Cons: no shared search ranking — Obsidian's quick-switcher and Claude's grep are different relevance models.
  • Obsidian + cyanheads/obsidian-mcp-server — GitHub. 14 MCP tools (obsidian_search_notes, obsidian_get_note, surgical patches via obsidian_patch_note, frontmatter/tag managers). Agent edits route through Obsidian's REST API plugin so the human sees changes on the next refresh. Auth is a single API key — no granular scopes. Conflict resolution = last-write-wins. Strongest AX you can get on top of Obsidian today.

3b. Single backend, multi-surface (shared ranking, multiple frontends)

The cleanest production pattern. One search engine, three faces.

  • tobi/qmd (GitHub, Tobias Lütke) — local hybrid search (BM25 + vector + LLM rerank) with three surfaces from the same index:

    • CLI for shell/agent access (qmd "query" → ranked markdown hits)
    • MCP server for native Claude/Cursor/Codex integration (GitHub: ehc-io/qmd)
    • Raycast extension for human Spotlight-style search
    • TUI variant (lazyqmd) for terminal-resident humans
    • Obsidian plugin (obsidian-qmd) for in-vault semantic search

    Single ranking model, four UIs, all talking to the same index. This is the closest thing to a dual-audience wiki search shipped in 2026. Caveat: it's search-only — no edit, no graph view, no orchestration.

3c. Bidirectional graph + human DB sync (highest ambition, smallest user base)

  • Synapse (Juan Dávila Gómez) — Neo4j knowledge graph (agent-native) ↔ Notion databases (human-native), bidirectional sync via Notion MCP. The agent extracts entities from conversations and writes to Neo4j; export designs custom Notion schemas (e.g., a "Medications" database emerges if conversations focus on health); every AI-written row gets a Needs Review checkbox + Correction Notes field; corrections flow back to invalidate Neo4j facts. Lessons from the project that matter for Hussh:
    • "The concept of a graph is great for understanding relationships, [but] navigating a massive raw graph view is for machines, not humans." → humans want tables, agents want graphs.
    • Human-in-the-loop checkboxes (Needs Review / Correction Notes) are the bridge between agent confidence and human ground truth. We have a less formalized version of this in our private open-questions ledger, which numbers each unresolved finding.
    • The painful part was lifecycle: running a Node.js MCP subprocess inside a Python backend with secure token handling.
  • Penfield (dev.to/penfieldlabs) — newer entrant, persistent typed knowledge graph behind an MCP. Their critique of Karpathy's wiki (untyped wikilinks, no cross-session graph memory) drives their product. Has agent surface but no first-class human UI yet.
  • GitNexus (MarkTechPost) — code-graph variant. Drop a repo in the browser, get a knowledge graph + MCP. Single-audience for now (mainly agent).

3d. Conversational wiki (NotebookLM-style)

  • Google NotebookLM — humans upload sources, ask questions, get podcasts/summaries/Q&A. Strong UX. AX is implicit (the model is the agent, the human is the user). Currently no MCP / agent-callable surface that lets a third-party agent query someone's NotebookLM. Closed loop. Worth tracking; not currently buildable on.
  • Mem.ai / Reflect / Granola — human-first; agent surfaces are limited to "AI features inside the app" rather than agent-callable APIs.

4. What's missing across the field

The Pixelmojo guide is candid: "No independent agency has published a named, referenceable AX methodology with its own terminology and framework" — and crucially, the article gives zero case studies of products that successfully serve both human and agent users from a single interface. Same observation in our search: the dual-audience wiki search is identified as the right thing, with weak examples.

Specific gaps:

  1. No standard for ranking explainability across surfaces. Humans want a "why this?" badge; agents want a confidence float. Different fields, no canonical schema.
  2. Auth/scopes don't yet bridge. Most MCP servers expose either "all" or "nothing" to agents; humans expect per-page permissions. No common middleware.
  3. Graph views collapse into tables for humans, then back into graphs for agents. Synapse paid this cost; the field hasn't generalized it.
  4. No streaming search-as-you-type with structured per-keystroke output for agents. Humans get incremental results; agents typically wait for batch.

5. Recommendation for the Hussh wiki

Today (5-minute investment, high payoff):

  1. Install Obsidian, point it at the local Hussh wiki repository. Free, native markdown, graph view shows all the cross-links we already have, frontmatter is queryable via the Dataview plugin. This is the human UX upgrade that costs nothing.

This week (medium investment): 2. Add cyanheads/obsidian-mcp-server so Claude Code can use surgical patches (obsidian_patch_note against headings) instead of full Read+Write cycles. Reduces token cost on edits and lowers risk of accidental rewrites. Auth = single API key in env var (PCHP-consistent if scoped properly). 3. Codify the dual-audience search behavior in the schema page — when a human asks via Obsidian's quick-switcher vs when Claude is asked via prompt, the answer should come from the same index and use the same ranking. Today this isn't enforced because the two use different mechanisms (Obsidian's fuzzy match vs Claude's grep).

At ~150 pages (deferred until it matters): 4. Install qmd locally and wire all three surfaces — CLI for shell, MCP for Claude, Raycast extension for human Spotlight-style search. Single hybrid-ranked backend, three surfaces. This is the dual-audience wiki search pattern fully realized. 5. Adopt Synapse's Needs Review / Correction Notes pattern — formalize the open-questions ledger's numbering scheme as an Obsidian Dataview field on every page that has open questions. Humans see a "needs review" badge; agents emit JSON with confidence: <float> and unverified_relations: [...].

Probably never (intentional): 6. No NotebookLM mirror. Closed loop, no MCP, doesn't fit BYOA. 7. No Penfield-style external knowledge graph backend until we cross several hundred entities — current Relations blocks are sufficient. 8. No automated scraping of Slack / email into the wiki. PCHP discipline ("no silent data flows") is more important than the convenience.

6. Specific design pattern: a Hussh wiki search box that serves both

If we built one tomorrow, here's the spec:

Backend: qmd over the wiki markdown tree, plus a thin wrapper that:

  • Indexes frontmatter as facets (type:, Status as of:).
  • Treats Sources blocks as authority signals (boost results with more sources).
  • Treats open-questions-ledger references as flags (downweight contradicted claims).

Human surface (UX):

  • Raycast extension ⌘ + space → search-as-you-type.
  • Each result card shows: page title, TL;DR, status, source count, "needs-review" badge if any.
  • ⏎ opens in Obsidian.
  • ⌘+enter copies a markdown link.

Agent surface (AX):

  • MCP tool wiki_search(query, filters?, max_results?, since_date?) returning JSON: 
    {
  "results": [
    {"path": "wiki/people/contact-x.md", "title": "Contact X",
     "tldr": "Engagement-lead partner...", "score": 0.91,
     "status_as_of": "2026-05-02", "sources": ["<internal source ref>"],
     "needs_review": true, "type": "reference"}
  ],
  "total_matches": 7, "next_page_token": null
}
  • Companion tools: wiki_read(path, sections?), wiki_relations(path, depth=1), wiki_audit(claim, page).

Shared: index, ranking model, auth, status-as-of staleness signal, VF-flag downweighting.

This is buildable on qmd + ~200 lines of wrapper + the existing Hussh wiki structure. Not now — but a clear destination.

Sources