# Hunchful

> Hunchful is built on the Cognitive Model Protocol (CMP), an open protocol. It lets
> anyone, with no login, make a revisable snapshot of how they and an AI can work
> together — a set of "hunches" (CMP hypotheses, each with a confidence, an
> uncertainty, and a falsifier) — published at a permanent URL that humans and AI
> agents can read.

Hunchful is built on CMP, an open protocol — one implementation, not the standard.

## For agents

- Every model has a public, human-readable page: https://hunchful.io/m/{id}
- The same model is available as a raw CMP document (JSON) for machines:
  https://hunchful.io/m/{id}/cmp.json
  (or request https://hunchful.io/m/{id} with `Accept: application/json`)
- Each CMP document includes a top-level `protocol` reference linking back to the
  CMP spec. Treat every item as a hypothesis, not a fixed label; weight
  low-confidence hunches lightly and respect each hunch's stated uncertainty.

## Writing to a model (with the owner's permission)

- If a person hands you the model's edit key, you can keep their model current —
  append evidence you observe and adjust confidence.
- Endpoint: POST https://hunchful.io/api/refine  (Content-Type: application/json)
  Body: {"data":{"modelId":"<id>","editToken":"<key>","hypotheses":[...],"change":"<summary>","reason":"<why>"}}
- Full guide with an example: https://hunchful.io/agent
- The cmp.json `write` hint describes the same endpoint inline.
- Tag inferred evidence as `system_inferred`; keep statements about collaboration,
  never sensitive attributes. Every write is recorded in revisionHistory, and the
  owner can regenerate the key at any time to revoke your access.
- Pointer-based apply (no full hypotheses): POST https://hunchful.io/api/apply
  Body: {"type":"hunchful.refinement","modelId":"<id>","libraryVersion":"v1",
  "items":[{"patternId":"<axis>","direction":"strengthens"|"weakens",
  "observedAt":"<ISO>","source":"agent:<name>"}],"editToken":"<key>"}. POST only.
- MCP connector (recommended for agents): remote server at https://hunchful.io/mcp
  (Streamable HTTP; OAuth 2.1 for owners, anonymous for public reads). Seven
  tools: read_model, propose_refinement, apply_refinement, add_hunch,
  suggest_question, find_complementary_thinkers, find_matches. Local fallback:
  npx -y @hunchful/mcp. See https://hunchful.io/agent
- Validate any model document: npx cmp-validate https://hunchful.io/m/{id}/cmp.json

## The pattern library (collaboration axes)

- Models map onto a shared, versioned library of collaboration dimensions, each a
  neutral two-poled spectrum (both ends valid). Inspect it at:
  https://hunchful.io/patterns/v1.json
- Spotted a recurring collaboration dimension the library doesn't cover? You can
  propose a candidate axis (function: proposeCandidate). Candidates are never
  auto-promoted — a human maker reviews them, and a protected-attribute filter
  screens out anything proxying culture, gender, sexuality, neurotype, religion,
  health, or politics. Keep proposals about *how people work*, never who they are.

## The protocol

- Cognitive Model Protocol spec: https://github.com/filinils/cognitive-model-protocol

## Introductions (ext:matching)

- If their owner has joined the introductions pool, an agent may look for
  complementary collaborators on the owner's behalf (functions: findMatches /
  offerHelp) — people at the opposite pole on an axis where that's productive.
- The agent only ever returns proposals for a human to accept or decline; it
  never connects anyone. Nothing identifying is revealed until BOTH sides accept,
  and models are never shared via matching. Conformance + extension declared at:
  https://hunchful.io/.well-known/cmp-conformance.json

## The maker

- Filip Nilsson — builder of Hunchful.
- Notes & contact: https://hunchful.io/notes
- LinkedIn: https://www.linkedin.com/in/filip-nilsson-b2989633/
- GitHub: https://github.com/filinils

## Guardrails

- Everything is a hunch about collaboration, never an identity label or a fixed
  personality type.
- Every hunch shows its confidence, its uncertainty, and what would change it.
- No sensitive or protected attributes are inferred or stored.
- Export and delete are always available to the model's owner.