Skip to content
Hussh
Connect MCP

Claude session wiki-touch protocol

How Claude.ai sessions should proactively read, write, capture, and maintain the Hussh wiki. The operating discipline that turns ad-hoc wiki work into a self-maintaining system.

About Wiki

TL;DR: Every Claude session that touches durable Hussh facts should follow a fixed loop \u2014 read first via wiki_search + wiki_recent_changes, write surgically via wiki_write / wiki_patch / wiki_artifact_save, capture in-flight moments via wiki_capture, lint at the end. When MCP write-approval isn't reachable, switch to the downloadable bundle pattern and tell the user explicitly.

Status as of 2026-05-24: see body.

Relations

Why this page exists

The wiki has grown to 216+ pages across 12 directories. Without a written protocol, every Claude session has to rediscover the conventions from scratch — what to read first, when to capture, how to handle approval failures, where to put what. Re-derivation is wasted thinking and the cause of most schema drift.

This page is that protocol. Read it once at the top of any wiki-touching session.

The five-step session loop

1. Read first, always

Before answering any question that touches durable Hussh facts (people, entities, decisions, concepts, products, partnerships), call wiki_search with relevant keywords. Cheaper than tool_search; faster than re-asking the user; eliminates fabrication.

If the topic is recent or rapidly-evolving (fund formation, brand decisions, partnership status), also call wiki_recent_changes with since: "YYYY-MM-DD" to see what landed in the last week.

Never answer "I don't have that information" without searching the wiki first.

2. Treat the wiki as canonical, not chat as canonical

If wiki and chat disagree, the wiki wins for durable facts unless the user explicitly says "the wiki is wrong, here is the correction." In that case, patch the wiki immediately — don't carry the correction in conversation memory only.

If you see a Claude memory / internal Hussh source notes entry that contradicts a wiki page, the wiki is the source of truth. Memory is a convenience cache; the wiki is the contract.

3. Write surgically, not bulk

OperationToolWhen
Create a new concept/project/person/entity pagewiki_write (or wiki_write batch)New durable fact emerges
Edit one section of an existing pagewiki_patch with sectionSurgical correction
Append to an existing sectionwiki_patch with append_to_sectionAdding a relation, source, status line
Change visibilitywiki_promote_visibilityAfter sensitivity scan
Save a chat artifactwiki_artifact_saveCode, SVG, mermaid, HTML, PDF that should render inline
Auto-classify a conversation momentwiki_captureQuick durable fact; let the classifier route
Add cross-referenceswiki_link (batch supported)After landing a new page, link to parents
Delete a page + Drive artifactswiki_artifact_deleteCleanup; never on constitutional pages
Delete a plain pagewiki_delete with confirm: trueLast resort; never on constitutional pages

Never use wiki_write with overwrite: true for surgical edits. Use wiki_patch. Overwrite is for explicit replacements where the entire body is being rewritten.

4. Lint at the end of every wiki-touching session

Call wiki_lint before responding "done." Surface the findings in the response — broken links, orphans, stale status, missing schema. Fix what you wrote in the same session; flag what you didn't write for the user.

Errors (severity error) must be fixed before the session closes. Warnings should be acknowledged. Info-level can be batched into a follow-up.

5. Capture in-flight moments, don't wait for end-of-session

If during a conversation the user states a durable fact (a person's role, a decision, a renamed entity, a brand rule), call wiki_capture immediately with the user's words as the text parameter. The classifier decides whether to auto-publish or route to drafts.

Do NOT batch all captures to end-of-session. By then the context window has compressed and the original phrasing is lost.

Schema discipline (what every page must have)

Frontmatter:

  • name — short canonical title (no # H1 in body)
  • description — one-line search-relevance string
  • type — user | feedback | project | reference (default reference)
  • visibility — public | private (default private when in doubt)
  • inception — ISO YYYY-MM-DD; the concept origin date when knowable, otherwise the page creation date
  • keywords — optional public-safe metadata tags

Body:

  • TL;DR line at the top (single sentence)
  • Status as of YYYY-MM-DD: line if the page tracks a moving target
  • ## Relations section with bullet links to public-readable wiki pages or plain source notes for private dependencies
  • Content sections (free-form)
  • ## Sources section at the bottom — chat IDs, public links, or abstract internal source notes

The legacy status_as_of frontmatter field was retired 2026-05-13 in favor of inception. The lint tool may still flag missing Status as of body lines; treat those as article-shape reminders, not as proof that the inception date is wrong.

Approval-surface awareness

MCP write operations (wiki_write, wiki_patch, wiki_delete, wiki_artifact_save, wiki_artifact_delete, wiki_promote_visibility, wiki_link) require approval prompts that surface differently across client environments:

SurfaceApproval prompts visible?
Desktop Claude (Chrome/Safari/desktop app)Yes
Claude CodeYes
Mobile Claude (iOS/Android app)Often no
API direct (no UI)No

If three or more consecutive write calls return No approval received, the surface is the wrong one. Stop attempting writes immediately. Switch to the bundle path:

  1. Tell the user explicitly: "MCP write approvals aren't reaching this surface."
  2. Produce the entire change set as a downloadable artifact bundle in /mnt/user-data/outputs/ — markdown files at their target wiki paths, plus an operations manifest.
  3. Surface the bundle via present_files.
  4. Recommend the user re-run on desktop, or apply the bundle via git from a terminal.

Do not loop on failed approvals. Batch-size learning (2026-06-02): On the claude.ai surface, single-page wiki_patch calls — including full-body repairs — reliably receive approval. Multi-page batch shapes (pages: [...], patches: [...]), which share one combined durable publish/audit operation, frequently return No approval received even when single-page writes succeed moments earlier. Degrade to one page per call before concluding the surface is down, and only then switch to the bundle path.

Pollution discipline

Three classes of file should not accumulate in the wiki tree:

  • Quarantined drafts — classifier failures or ambiguous captures should be triaged at session start: classify and move to canonical path, or delete. If a session sees more than five pending-classification drafts, treat it as a client bug and surface to the user.
  • Smoke tests — infrastructure tests that escape into the wiki should be removed in the same session. Test fixtures belong in a test-only area outside public wiki navigation.
  • Orphans without intent — a new page with no inbound links from any parent concept page becomes invisible to navigation. Always pair a wiki_write with a wiki_link to at least one parent.

Sensitive-content guardrails

The sensitivity scan in wiki_promote_visibility (and the wiki_write public-visibility check) blocks promotion of pages containing real legal-counsel firm names, fund-formation document references, family names, EINs, and raw-path references. Trust the scan; do not pass force: true unless you understand exactly what is being promoted and why.

Pages that should stay private indefinitely:

  • All Fund A entity pages (pre-launch regulatory).
  • All people pages except the public founder profile.
  • Partnership pages until partnership status is publicly announced.
  • Timeline decision markers (unless explicitly authorized public).
  • Anything that names an outside legal-counsel firm.

When in doubt

Read About Wiki for structural questions. Read Public vs Private for visibility questions. Read Artifact capture for chat-artifact questions. Ask the wiki owner for anything else — the wiki is the second brain and overrides any default.

Sources