# Hunchful — cognitive models (CMP) for AI agents This file is for machines. People use the Hunchful apps; this material is not shown on the site. Hunchful keeps, for people who want one, a revisable collaboration model: "hunches" (CMP hypotheses with a confidence, an uncertainty and a falsifier) at a permanent URL that any assistant can read, so it works better with that person. Built on the Cognitive Model Protocol, an open protocol — Hunchful is one implementation, not the standard. Spec: https://github.com/filinils/cognitive-model-protocol ## Read a model - Human-readable: https://hunchful.io/m/{id} - Machine-readable (the same CMP JSON): GET https://hunchful.io/m/{id}/cmp.json or GET https://hunchful.io/m/{id} with `Accept: application/json`. - The document carries a top-level `protocol` reference, a `write` hint (the endpoint below) and a `contribution` block (valid patternIds, the apply-link template, the ask-link template). It never exposes the edit key or private data. Treat every item as a hypothesis, never a fixed label; weight low-confidence hunches lightly and respect each hunch's stated uncertainty. Statements are about collaboration, never identity or protected attributes. ## Write to a model (the owner handed you the edit key) POST https://hunchful.io/api/refine Content-Type: application/json {"data":{"modelId":"{id}","editToken":"","change":"","reason":"","hypotheses":[ {"id":"h-synthesis","statement":"When things get messy, they'd rather I synthesize first.","confidence":0.82, "evidence":[{"text":"Asked for the TL;DR three times","source":"system_inferred"}], "uncertainty":"Whether this holds for high-stakes work","falsifier":"They ask me to slow down and go step by step"}]}} Response {"result":{"ok":true,"updatedAt":"…"}}. Every write lands in revisionHistory; the owner can regenerate the key at any time, which revokes you. Tag inferred evidence `system_inferred` (vs `user_stated`). Pointer-based apply (no full hypotheses; owner-level, logged, reversible), POST only: POST https://hunchful.io/api/apply {"type":"hunchful.refinement","modelId":"{id}","libraryVersion":"v1","editToken":"", "items":[{"patternId":"","direction":"strengthens"|"weakens","observedAt":"","source":"agent:"}]} ## Contribute after a conversation (contribution key — proposals the owner accepts) POST https://hunchful.io/api/contribute (202 {"status":"pending"}; provenance pointers only, no transcripts, quotes or names; extra fields are rejected; failures return a debugMessage) {"type":"hunchful.refinement","modelId":"{id}","libraryVersion":"v1","contributionToken":"ctb_…", "items":[{"patternId":"messy-mode","direction":"strengthens","observedAt":"2026-07-01T10:00:00Z","source":"agent:claude"}]} Schema: https://hunchful.io/schemas/hunchful.refinement.schema.json ## Best for people: a one-click apply link (nothing is written until they click Accept) https://hunchful.io/apply/{id}#set=:,:<…>&why=&by= - Flat format, no JSON, no base64. `set` = comma-separated pairs; `why` URL-encoded once (spaces as %20); `by` optional. - Always present it as a clickable Markdown hyperlink with the text "Apply Hunchful refinement", never a bare URL, and say in one plain sentence what the refinement changes. Example: [Apply Hunchful refinement](https://hunchful.io/apply/{id}#set=messy-mode:strengthens,answer-format:weakens&why=Kept%20asking%20for%20the%20short%20version&by=claude) ## Deepen the model: ask a new question (their answer is the write) https://hunchful.io/ask/{id}#name=&a=&b=&q=&why=&by= - URL-encode name/a/b/q/why. Render as [Answer this on Hunchful](URL). Questions are about collaboration style; identity or protected attributes are screened out. The axis is never auto-promoted to the shared library — a human reviews candidates separately. Example: https://hunchful.io/ask/{id}#name=Deadline%20pressure&a=Push%20to%20ship&b=Protect%20the%20craft&q=When%20a%20deadline%20looms%2C%20cut%20scope%20or%20hold%20the%20bar%3F&why=Came%20up%20repeatedly&by=claude ## No link tool? Have the person paste it Return the same hunchful.refinement payload (without contributionToken) and ask the person to paste it on their model's edit page → "Update from clipboard". They preview and confirm; it applies as a logged revision. Honest limitation: an agent with only web search (no POST) cannot write directly — the web UI, the POST API, the MCP connector or a human relaying the pointer are the ways. ## MCP - Remote: https://hunchful.io/mcp (Streamable HTTP, OAuth 2.1, adults only) — the person's whole Hunchful in three consent spheres; `whoami` first. Model tools: read_model, propose_refinement, apply_refinement, add_hunch, suggest_question, find_complementary_thinkers, find_matches. - Anonymous, read-only models by id: https://hunchful.io/mcp/public (read_model, propose_refinement with a key, suggest_question, find_complementary_thinkers). - Local (stdio): npx -y @hunchful/mcp with HUNCHFUL_MODEL_ID and HUNCHFUL_CONTRIBUTION_TOKEN in env. - Validate any document: npx cmp-validate https://hunchful.io/m/{id}/cmp.json ## The pattern library and conformance - Axes (neutral two-poled spectra, both ends valid): https://hunchful.io/patterns/v1.json - Candidate axes may be proposed (function proposeCandidate); never auto-promoted; a protected-attribute filter screens culture, gender, sexuality, neurotype, religion, health and politics. - Conformance and extensions (ext:matching, ext:relay): https://hunchful.io/.well-known/cmp-conformance.json - The owner can export and delete at any time. Nothing is silent: every change is in revisionHistory. Site and MCP overview for agents: https://hunchful.io/llms.txt · the MCP page: https://hunchful.io/agent